Added the standard documentation policy and a roadmap for adding documentation
This commit is contained in:
2
LICENSE
2
LICENSE
@@ -1,4 +1,4 @@
|
||||
Copyright (c) 2026 eric.
|
||||
Copyright (c) 2026 Eric Rakestraw.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
|
||||
|
||||
|
||||
219
docs/policy/architecture.md
Normal file
219
docs/policy/architecture.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Architecture Policy
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines seriatim's development architecture and invariants for
|
||||
maintainers and automated coding agents. It describes how the implemented
|
||||
system is intended to be built and changed. It is not a user manual, CLI
|
||||
reference, config reference, or roadmap.
|
||||
|
||||
Keep this document aligned with [documentation policy](documentation.md). It
|
||||
must describe current behavior only; planned or speculative work belongs under
|
||||
`docs/roadmap/`.
|
||||
|
||||
## Project Shape
|
||||
|
||||
seriatim is a Go CLI for transcript artifact processing. The implemented
|
||||
commands are `merge`, `trim`, and `normalize`.
|
||||
|
||||
`merge` reads one or more JSON transcript files, optionally maps input files to
|
||||
canonical speakers, runs a registry-selected preprocessing chain, merges
|
||||
canonical segments into deterministic chronological order, runs a
|
||||
registry-selected postprocessing chain, validates the selected output schema,
|
||||
and writes JSON output plus an optional JSON report.
|
||||
|
||||
`trim` and `normalize` are artifact-level commands outside the merge pipeline.
|
||||
`trim` reads an existing seriatim output artifact and projects it by segment ID.
|
||||
`normalize` reads transcript-like JSON and emits one of seriatim's supported
|
||||
output schemas. Neither command runs merge preprocessing or postprocessing
|
||||
modules.
|
||||
|
||||
The supported public output schemas are `seriatim-minimal`,
|
||||
`seriatim-intermediate`, and `seriatim-full`. For current command and flag
|
||||
details, use [the README](../../README.md) until dedicated `docs/cli.md` and
|
||||
`docs/config.md` files exist.
|
||||
|
||||
## Core Design Principles
|
||||
|
||||
- Keep a hexagonal architecture boundary. Domain models, stage contracts, and
|
||||
deterministic transformations must stay separate from CLI parsing,
|
||||
filesystem access, config loading, reporting, and other external adapters.
|
||||
- Keep stages and modules composable. Built-in modules are selected by
|
||||
canonical registry names and implement explicit interfaces for their pipeline
|
||||
role.
|
||||
- Preserve deterministic behavior. Given the same inputs, configuration, and
|
||||
version, output ordering, segment IDs, schema validation, and report event
|
||||
ordering should remain stable.
|
||||
- Current command execution is sequential. There is no scheduler, worker pool,
|
||||
or concurrent module execution in the implemented pipeline. Any concurrency
|
||||
added later must be bounded, observable, and must not make output handling
|
||||
nondeterministic.
|
||||
- Prefer the Go standard library. Third-party dependencies should remain narrow
|
||||
and justified, such as Cobra for CLI structure, YAML parsing, and JSON Schema
|
||||
validation.
|
||||
- Document current behavior. Architecture, user, and internal docs must not
|
||||
describe planned features as implemented behavior.
|
||||
|
||||
## Architectural Boundaries
|
||||
|
||||
Core transcript data belongs in `internal/model` and public artifact contracts
|
||||
belong in `schema`. Conversion from internal merged data to public JSON shapes
|
||||
belongs at the artifact boundary, not inside CLI code or transformation
|
||||
packages.
|
||||
|
||||
Pipeline orchestration belongs in `internal/pipeline`. It resolves registered
|
||||
modules, validates preprocessing state transitions, executes stages in order,
|
||||
collects report events, converts the final transcript, and writes optional
|
||||
reports. Built-in adapters and modules are registered from `internal/builtin`.
|
||||
|
||||
CLI code in `internal/cli` should parse flags, build validated config values,
|
||||
and delegate. `merge` delegates to `pipeline.Run`; `trim` and `normalize`
|
||||
perform artifact-level orchestration and delegate deterministic parsing,
|
||||
validation, and transformation work to their internal packages.
|
||||
|
||||
Config loading and validation belongs in `internal/config`. Filesystem reads and
|
||||
writes are adapter concerns and should not spread into pure transformation
|
||||
helpers. Existing built-in modules that load configured YAML files must keep
|
||||
that I/O narrow and explicit.
|
||||
|
||||
Reports belong in `internal/report`. Modules and commands should emit concise
|
||||
events for validation findings, corrections, and transformations without
|
||||
turning report messages into a duplicate output artifact.
|
||||
|
||||
Tests and samples are supporting evidence for behavior. Tests should verify
|
||||
stable contracts and edge cases; samples should remain valid examples, not
|
||||
hidden architecture dependencies.
|
||||
|
||||
## Modules or Stages
|
||||
|
||||
The merge pipeline has these implemented stages:
|
||||
|
||||
- `InputReader`: reads configured external input into raw transcripts.
|
||||
- `Preprocessor`: transforms `PreprocessState` from raw to canonical state.
|
||||
- `Merger`: combines canonical transcripts into one merged transcript.
|
||||
- `Postprocessor`: transforms or annotates the merged transcript.
|
||||
- `OutputWriter`: writes the selected output artifact.
|
||||
|
||||
Modules must keep narrow responsibilities, declare their stage through the
|
||||
interface they implement, and use explicit config values. Preprocessors must
|
||||
declare `Requires()` and `Produces()` states; the runner rejects invalid
|
||||
raw/canonical ordering before processing completes.
|
||||
|
||||
Modules run in the configured order. Order-affecting modules must run before
|
||||
`assign-ids`, and `validate-output` must see final IDs that match the selected
|
||||
schema. Accepted and rejected transformations should be deterministic and, when
|
||||
observable, recorded through report events.
|
||||
|
||||
Transformation helpers should avoid hidden global state. Shared caches, such as
|
||||
compiled JSON schemas, must be protected and must not affect output ordering.
|
||||
|
||||
## State, Inputs, and Outputs
|
||||
|
||||
seriatim is file-based. It reads JSON inputs and optional YAML rule files, then
|
||||
writes JSON transcript artifacts and optional JSON reports.
|
||||
|
||||
The implemented application has no durable database, daemon state, resume
|
||||
state, remote storage, or background job state. Runtime state is held in memory
|
||||
for the current command invocation and serialized only through requested output
|
||||
and report files.
|
||||
|
||||
Input file paths are normalized and validated during config construction.
|
||||
`merge` sorts input file paths before processing, then uses stable segment sort
|
||||
keys. `trim` preserves transcript order while renumbering retained IDs.
|
||||
`normalize` sorts by implemented deterministic keys and assigns fresh IDs.
|
||||
|
||||
## Configuration and CLI Boundaries
|
||||
|
||||
The CLI surface is an adapter over validated config structs. Cobra command code
|
||||
should stay thin: parse flags, account for flag/default precedence, call config
|
||||
constructors, and delegate.
|
||||
|
||||
Config constructors validate required paths, output parent directories, module
|
||||
lists, selected schemas, mutually exclusive trim selector options, and supported
|
||||
environment-derived settings. Module name validation is split between config
|
||||
where command-specific names are fixed and the pipeline registry where module
|
||||
composition is resolved.
|
||||
|
||||
Do not duplicate full CLI or config reference material here. Use
|
||||
[the README](../../README.md) for the current user-facing reference until the
|
||||
canonical `docs/cli.md` and `docs/config.md` files exist.
|
||||
|
||||
## Errors, Logging, and Diagnostics
|
||||
|
||||
Commands return errors instead of printing inside deep logic. The root command
|
||||
silences Cobra usage/error output, and `cmd/seriatim/main.go` prints one error
|
||||
to stderr and exits with status `1`.
|
||||
|
||||
Validation failures should fail fast with contextual errors. Correctable
|
||||
conditions should be deterministic and, where reports are requested, reflected
|
||||
as report events. Optional reports contain metadata and ordered events; they are
|
||||
not required for command success unless the report file itself cannot be
|
||||
written.
|
||||
|
||||
The implemented code does not use a logging subsystem. Diagnostics are returned
|
||||
as errors or written to optional report JSON. Normalize report events avoid
|
||||
embedding transcript text; keep that privacy-oriented behavior when changing
|
||||
normalize diagnostics.
|
||||
|
||||
## Testing Expectations
|
||||
|
||||
`go test ./...` is the repository-wide check. There is currently no Makefile,
|
||||
taskfile, linter config, or dedicated documentation check.
|
||||
|
||||
When changing config or CLI behavior, inspect `internal/config` and
|
||||
`internal/cli` tests. When changing pipeline composition or stage contracts,
|
||||
inspect `internal/pipeline` and `internal/builtin` tests. When changing
|
||||
correction or annotation modules, inspect the package tests for overlap,
|
||||
coalesce, danglers, backchannel, filler, and autocorrect behavior.
|
||||
|
||||
When changing artifact-level commands, inspect `internal/trim`,
|
||||
`internal/normalize`, and their CLI tests. When changing public output shape or
|
||||
schema validation, inspect `schema` and `internal/artifact` tests. Report and
|
||||
diagnostic changes should be covered through the command or package tests that
|
||||
emit the affected events.
|
||||
|
||||
## Dependency Policy
|
||||
|
||||
Prefer the Go standard library for parsing, data transformation, concurrency
|
||||
primitives, filesystem work, and testing wherever it is reasonable.
|
||||
|
||||
Third-party dependencies must be narrow, justified, and preferably de facto
|
||||
standard for their purpose. Existing examples include Cobra for CLI structure,
|
||||
`gopkg.in/yaml.v3` for YAML files, and `jsonschema/v6` for validating embedded
|
||||
public JSON schemas. Avoid broad framework dependencies for behavior that is
|
||||
already simple and local.
|
||||
|
||||
## Documentation Expectations
|
||||
|
||||
Architecture docs must stay aligned with [documentation policy](documentation.md).
|
||||
Current-behavior docs must not become aspirational. If code and docs disagree,
|
||||
fix the inaccurate current-behavior doc or put planned work under
|
||||
`docs/roadmap/`.
|
||||
|
||||
Prefer links to canonical docs instead of repeating full CLI, config, schema, or
|
||||
operations reference material. Keep examples real, tested where practical, and
|
||||
free of secrets or private transcript data.
|
||||
|
||||
## Architectural Invariants
|
||||
|
||||
- Keep core/domain logic separate from CLI, config, filesystem, reporting, and
|
||||
other adapter concerns.
|
||||
- Keep modules narrowly scoped, explicitly configured, and composable by
|
||||
registry name.
|
||||
- Preserve deterministic ordering, final segment ID assignment, and schema
|
||||
validation before output acceptance.
|
||||
- Keep `trim` and `normalize` artifact-level; do not run merge modules from
|
||||
those commands.
|
||||
- Keep public output schemas validated through `schema`.
|
||||
- Keep optional reports ordered, concise, and diagnostic.
|
||||
- Avoid broad dependencies without a concrete maintainability benefit.
|
||||
- Do not document unimplemented behavior outside `docs/roadmap/`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
The implemented application does not perform transcription, audio diarization,
|
||||
speaker inference from audio or text, summarization, daemon operation, remote
|
||||
storage, dynamic external plugin loading, or concurrent pipeline execution.
|
||||
|
||||
The architecture policy is not a package-by-package reference, CLI manual,
|
||||
config reference, schema reference, or roadmap.
|
||||
356
docs/policy/documentation.md
Normal file
356
docs/policy/documentation.md
Normal file
@@ -0,0 +1,356 @@
|
||||
# Go Project Documentation Policy
|
||||
|
||||
## Purpose
|
||||
|
||||
Project documentation must help four audiences:
|
||||
|
||||
1. users who need to run the application;
|
||||
2. administrators/operators who need to configure and operate it;
|
||||
3. developers who need to understand and change it safely;
|
||||
4. LLM coding agents that need clear scope, boundaries, and invariants.
|
||||
|
||||
Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
|
||||
|
||||
## Core Rules
|
||||
|
||||
### 1. Keep docs concise
|
||||
|
||||
Each document should cover a defined scope and only the essentials for that scope.
|
||||
|
||||
Avoid:
|
||||
- long background explanations;
|
||||
- repeated reference material;
|
||||
- implementation detail in user-facing docs;
|
||||
- aspirational language outside roadmap docs;
|
||||
- verbose examples where one minimal example is clearer.
|
||||
|
||||
### 2. Document only implemented behavior outside roadmap files
|
||||
|
||||
Unimplemented, planned, aspirational, experimental, or future work may be described only under:
|
||||
|
||||
- `docs/roadmap/`
|
||||
|
||||
No other documentation file, including `README.md`, should describe code, features, modules, stages, commands, config fields, or behaviors that do not currently exist.
|
||||
|
||||
If a feature is partial, non-roadmap docs may describe only the implemented portion and its current boundary.
|
||||
|
||||
### 3. Use canonical homes
|
||||
|
||||
Each type of information should have one canonical location.
|
||||
|
||||
Canonical homes:
|
||||
|
||||
- project purpose and quickstart: `README.md`
|
||||
- development principles: `docs/policy/architecture.md`
|
||||
- configuration reference: `docs/config.md`
|
||||
- CLI reference: `docs/cli.md`
|
||||
- operations and recovery: `docs/operations.md`
|
||||
- troubleshooting: `docs/troubleshooting.md`
|
||||
- implemented internals: `docs/internal/`
|
||||
- future work: `docs/roadmap/`
|
||||
- contributor workflow: `docs/policy/development.md`
|
||||
- copyable examples: `examples/`
|
||||
|
||||
Other files should summarize briefly and link to the canonical source.
|
||||
|
||||
### 4. Keep examples real
|
||||
|
||||
Examples should be valid, maintained, and free of secrets.
|
||||
|
||||
Where practical:
|
||||
- example configs should load successfully;
|
||||
- example commands should match real CLI syntax;
|
||||
- important examples should be covered by tests.
|
||||
|
||||
## Documentation Profiles
|
||||
|
||||
All projects require:
|
||||
|
||||
- `README.md`
|
||||
- `docs/policy/architecture.md`
|
||||
|
||||
Additional docs depend on the project.
|
||||
|
||||
### Small library
|
||||
|
||||
Recommended:
|
||||
- `docs/policy/development.md`, if contributor conventions are non-obvious
|
||||
|
||||
### Simple CLI
|
||||
|
||||
Required:
|
||||
- `docs/cli.md`
|
||||
|
||||
Recommended:
|
||||
- `docs/policy/development.md`
|
||||
|
||||
### Config-driven CLI
|
||||
|
||||
Required:
|
||||
- `docs/cli.md`
|
||||
- `docs/config.md`
|
||||
|
||||
Recommended:
|
||||
- `examples/`
|
||||
- `docs/policy/development.md`
|
||||
|
||||
### Stateful or operator-facing application
|
||||
|
||||
Required:
|
||||
- `docs/cli.md`, if CLI-based
|
||||
- `docs/config.md`, if config-driven
|
||||
- `docs/operations.md`
|
||||
|
||||
Recommended:
|
||||
- `docs/troubleshooting.md`
|
||||
- `examples/`
|
||||
- `docs/policy/development.md`
|
||||
|
||||
### Modular, staged, service-oriented, or orchestration application
|
||||
|
||||
Required:
|
||||
- `docs/cli.md`, if CLI-based
|
||||
- `docs/config.md`, if config-driven
|
||||
- `docs/operations.md`
|
||||
- `docs/internal/`
|
||||
- `docs/policy/development.md`
|
||||
|
||||
Recommended:
|
||||
- `docs/troubleshooting.md`
|
||||
- validated examples under `examples/`
|
||||
|
||||
## Required Documents
|
||||
|
||||
### README.md
|
||||
|
||||
**Audience:** users, administrators, operators
|
||||
|
||||
The README is the outward-facing project orientation page.
|
||||
|
||||
It should include, in order:
|
||||
|
||||
1. concise description;
|
||||
2. elevator pitch;
|
||||
3. shortest useful command or usage example;
|
||||
4. links to targeted docs.
|
||||
|
||||
The README should be short. It is not a manual.
|
||||
|
||||
The “shortest useful command” means the simplest command that performs the project’s core use case. (It does not mean `app --help`.)
|
||||
|
||||
### docs/policy/architecture.md
|
||||
|
||||
**Audience:** developers, LLM coding agents
|
||||
|
||||
`docs/policy/architecture.md` is required for every project.
|
||||
|
||||
It is an inward-facing development policy document. It should describe how the project is intended to be built and changed.
|
||||
|
||||
It should include:
|
||||
|
||||
- project shape;
|
||||
- core design principles;
|
||||
- package and boundary philosophy;
|
||||
- state/persistence philosophy, if applicable;
|
||||
- external integration philosophy, if applicable;
|
||||
- error-handling and logging principles;
|
||||
- testing expectations;
|
||||
- documentation expectations;
|
||||
- architectural invariants;
|
||||
- explicit non-goals, if useful.
|
||||
|
||||
For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light.
|
||||
|
||||
### docs/policy/development.md
|
||||
|
||||
**Audience:** developers, LLM coding agents
|
||||
|
||||
Required for projects maintained by humans and LLM coding agents.
|
||||
|
||||
It should include:
|
||||
|
||||
- repository layout;
|
||||
- build/test commands;
|
||||
- coding conventions;
|
||||
- dependency policy;
|
||||
- how to add config fields;
|
||||
- how to add CLI flags;
|
||||
- how to add stages/modules/adapters, if applicable;
|
||||
- how to update examples;
|
||||
- documentation update expectations.
|
||||
|
||||
### docs/config.md
|
||||
|
||||
**Audience:** administrators, operators, advanced users
|
||||
|
||||
Required for applications with configuration files.
|
||||
|
||||
It should include, in order:
|
||||
|
||||
1. config file locations and discovery precedence;
|
||||
2. minimal working config;
|
||||
3. production-oriented config;
|
||||
4. full configuration reference;
|
||||
5. secrets handling, if applicable;
|
||||
6. links to maintained examples.
|
||||
|
||||
The full configuration reference should be canonical.
|
||||
|
||||
### docs/cli.md
|
||||
|
||||
**Audience:** users, administrators, operators
|
||||
|
||||
Required for CLI applications.
|
||||
|
||||
It should include, in order:
|
||||
|
||||
1. shortest useful command;
|
||||
2. command overview;
|
||||
3. complete flag reference;
|
||||
4. common workflows;
|
||||
5. diagnostic or recovery commands, if applicable.
|
||||
|
||||
Explain when commands are useful, not just their syntax.
|
||||
|
||||
### docs/operations.md
|
||||
|
||||
**Audience:** administrators, operators
|
||||
|
||||
Required for applications that maintain state, support resume behavior, run multiple stages, write durable artifacts, use remote storage, or require recovery procedures.
|
||||
|
||||
It should cover:
|
||||
|
||||
- normal workflow;
|
||||
- filesystem layout;
|
||||
- remote storage layout, if applicable;
|
||||
- logs and manifests;
|
||||
- resume/retry behavior;
|
||||
- cleanup behavior;
|
||||
- archive/backup behavior;
|
||||
- safe recovery procedures;
|
||||
- operational caveats.
|
||||
|
||||
### docs/troubleshooting.md
|
||||
|
||||
**Audience:** administrators, operators
|
||||
|
||||
Recommended once recurring failure modes exist.
|
||||
|
||||
Each entry should include:
|
||||
|
||||
- symptom;
|
||||
- likely cause;
|
||||
- diagnostic command or inspection step;
|
||||
- safe fix;
|
||||
- relevant links.
|
||||
|
||||
### docs/internal/
|
||||
|
||||
**Audience:** developers, LLM coding agents
|
||||
|
||||
Required for modular, staged, service-oriented, or orchestration projects.
|
||||
|
||||
This directory describes implemented internal components. It is not the roadmap.
|
||||
|
||||
Use one file per major component where useful.
|
||||
|
||||
Each component doc should include:
|
||||
|
||||
1. purpose;
|
||||
2. inputs and outputs;
|
||||
3. boundaries;
|
||||
4. config fields used;
|
||||
5. external adapters used;
|
||||
6. state or manifest behavior, if applicable;
|
||||
7. skip/resume behavior, if applicable;
|
||||
8. failure behavior;
|
||||
9. tests to inspect before changing;
|
||||
10. architectural invariants.
|
||||
|
||||
### docs/roadmap/
|
||||
|
||||
**Audience:** maintainers, developers, LLM coding agents
|
||||
|
||||
This is the only place for planned, future, aspirational, experimental, or unimplemented work.
|
||||
|
||||
Roadmap docs should clearly distinguish:
|
||||
|
||||
- proposed work;
|
||||
- accepted plans;
|
||||
- deferred ideas;
|
||||
- rejected ideas;
|
||||
- implementation prompts or task breakdowns, if useful.
|
||||
|
||||
Roadmap docs should not be confused with current behavior.
|
||||
|
||||
### docs/integrations/
|
||||
|
||||
**Audience:** developers, LLM coding agents
|
||||
|
||||
Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
|
||||
|
||||
This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses.
|
||||
|
||||
Use one file per integration where useful.
|
||||
|
||||
## Examples Directory
|
||||
|
||||
Projects with non-trivial configuration or workflows should include `examples/`.
|
||||
|
||||
Useful examples include:
|
||||
|
||||
- minimal working config;
|
||||
- production-oriented config;
|
||||
- full annotated config;
|
||||
- local development config;
|
||||
- remote/object-storage config;
|
||||
- minimal session/input file.
|
||||
|
||||
Examples should be valid, maintained, tested when practical, and linked from relevant docs.
|
||||
|
||||
## Security and Privacy
|
||||
|
||||
Docs and examples must not include:
|
||||
|
||||
- real API keys;
|
||||
- tokens;
|
||||
- passwords;
|
||||
- private keys;
|
||||
- private environment dumps;
|
||||
- sensitive user data;
|
||||
- raw private transcripts;
|
||||
- private infrastructure details unless intentionally public.
|
||||
|
||||
Document secret-handling mechanisms, not actual secret values.
|
||||
|
||||
## Maintenance Rules
|
||||
|
||||
When docs change, verify the affected behavior.
|
||||
|
||||
Where practical:
|
||||
|
||||
- load example config files in tests;
|
||||
- test CLI examples or command parser behavior;
|
||||
- validate documented flags against real flags;
|
||||
- remove stale references;
|
||||
- update links after renames;
|
||||
- keep roadmap content out of non-roadmap docs.
|
||||
|
||||
If documentation and code disagree, fix the documentation and/or open a roadmap item; do not leave aspirational behavior in current-behavior docs.
|
||||
|
||||
Documentation is complete only when it matches the current code.
|
||||
|
||||
## Documentation Change Checklist
|
||||
|
||||
Before merging documentation changes, verify:
|
||||
|
||||
- README is concise and orientation-focused.
|
||||
- `docs/policy/architecture.md` describes development principles.
|
||||
- Future work appears only under `docs/roadmap/`.
|
||||
- User-facing docs avoid unnecessary internals.
|
||||
- Developer-facing docs preserve boundaries and invariants.
|
||||
- Config examples match the schema.
|
||||
- CLI examples match real commands and flags.
|
||||
- Defaults appear in the canonical config reference.
|
||||
- No secrets or private data are included.
|
||||
- Links are accurate.
|
||||
579
docs/roadmap/documentation.md
Normal file
579
docs/roadmap/documentation.md
Normal file
@@ -0,0 +1,579 @@
|
||||
# Documentation Roadmap
|
||||
|
||||
## Purpose
|
||||
|
||||
This roadmap defines the work required to bring seriatim's documentation into
|
||||
compliance with `docs/policy/documentation.md` and the current implementation.
|
||||
It is grounded in the repository as it exists now: the Go CLI, config loading,
|
||||
pipeline modules, artifact commands, schemas, reports, samples, and tests.
|
||||
|
||||
Outside `docs/roadmap/`, documentation must describe only implemented
|
||||
behavior. Planned, future, deprecated, experimental, or unimplemented work must
|
||||
remain in roadmap documents until the code exists.
|
||||
|
||||
## Repository Documentation Inventory
|
||||
|
||||
- `README.md` - keep and rewrite. It currently mixes project orientation,
|
||||
quickstart, full CLI reference, config/env reference, file formats, module
|
||||
internals, limitations, and release build notes. Policy says README should be
|
||||
concise and link to canonical docs.
|
||||
- `docs/policy/documentation.md` - keep and lightly update only if the policy
|
||||
itself changes. It is the controlling documentation layout and maintenance
|
||||
policy.
|
||||
- `docs/policy/architecture.md` - keep and lightly update as implementation
|
||||
changes. It is the canonical development architecture policy.
|
||||
- Root `architecture.md` - delete after salvage, or move only truly roadmap
|
||||
material into `docs/roadmap/`. It is in the wrong canonical home and contains
|
||||
future-oriented and aspirational claims.
|
||||
- `docs/roadmap/documentation.md` - create new. This file is the planning
|
||||
artifact for the documentation migration.
|
||||
- `samples/` - split or move after audit. It contains sample raw transcripts,
|
||||
merged artifacts, reports, `speakers.yml`, and `autocorrect.yml`, but
|
||||
copyable examples belong under `examples/`. The raw sample data is large and
|
||||
should be reviewed for privacy and maintainability before linking from docs.
|
||||
- `schema/*.schema.json` - keep. These are public output contracts and should
|
||||
be linked from documentation instead of duplicated in full.
|
||||
- Missing canonical docs - create `docs/cli.md`, `docs/config.md`,
|
||||
`docs/operations.md`, `docs/policy/development.md`, `docs/internal/`, and
|
||||
likely `docs/troubleshooting.md`, `docs/integrations/`, and `examples/`.
|
||||
|
||||
## Policy Compliance Assessment
|
||||
|
||||
Required documents missing for seriatim's current shape as a modular, staged,
|
||||
CLI/config-driven project:
|
||||
|
||||
- `docs/cli.md`
|
||||
- `docs/config.md`
|
||||
- `docs/operations.md`
|
||||
- `docs/internal/`
|
||||
- `docs/policy/development.md`
|
||||
|
||||
Recommended documents and directories missing:
|
||||
|
||||
- `docs/troubleshooting.md`
|
||||
- maintained copyable examples under `examples/`
|
||||
- concise integration notes under `docs/integrations/`
|
||||
|
||||
Existing compliance issues:
|
||||
|
||||
- `README.md` is too broad for its canonical scope. It should keep project
|
||||
purpose, quickstart, and links, then delegate CLI, config, operations,
|
||||
internals, and schema details.
|
||||
- Root `architecture.md` is stale and in the wrong home. It includes future
|
||||
input methods and formats, future output formats, dynamic plugin speculation,
|
||||
an LLM non-goal, interface sketches that diverge from code, and other
|
||||
development-policy content now covered by `docs/policy/architecture.md`.
|
||||
- Non-roadmap docs should not carry forward claims about future defaults,
|
||||
future formats, unimplemented plugin systems, or unimplemented alternate
|
||||
input/output methods.
|
||||
- Historical or deprecated wording, such as the old speaker map format, should
|
||||
move out of the README unless it is still needed in troubleshooting or a
|
||||
narrow migration note.
|
||||
- There is no `examples/` directory. `samples/` exists but is not the canonical
|
||||
examples home and should not be treated as copyable public examples without a
|
||||
privacy and size audit.
|
||||
- Links need verification after migration: README should link to all new
|
||||
canonical docs, docs should link to schema files and maintained examples, and
|
||||
no doc should link to the deleted root `architecture.md`.
|
||||
|
||||
## Target Documentation Set
|
||||
|
||||
### `README.md`
|
||||
|
||||
- Audience: users, administrators, and operators.
|
||||
- Purpose: project orientation and shortest useful quickstart.
|
||||
- Canonical scope: concise project purpose, elevator pitch, one minimal command,
|
||||
and links to targeted docs.
|
||||
- Recommended outline: project description; shortest merge command; command
|
||||
summary; links to CLI, config, operations, architecture, development, schemas,
|
||||
examples, and troubleshooting.
|
||||
- Source of truth: current `README.md`, `internal/cli`, `internal/config`,
|
||||
`cmd/seriatim/main.go`, and CLI tests.
|
||||
- Acceptance criteria: no full flag tables, no full config reference, no module
|
||||
manual, no future-feature claims, and all links resolve.
|
||||
|
||||
### `docs/cli.md`
|
||||
|
||||
- Audience: users, administrators, and operators.
|
||||
- Purpose: canonical CLI reference and workflows.
|
||||
- Canonical scope: shortest useful command, command overview, complete flag
|
||||
reference, common workflows, diagnostics and report flags.
|
||||
- Recommended outline: shortest useful command; global flags; `merge`; `trim`;
|
||||
`normalize`; common workflows; exit/error behavior; links to config,
|
||||
operations, examples, and schemas.
|
||||
- Source of truth: `internal/cli/root.go`, `internal/cli/merge.go`,
|
||||
`internal/cli/trim.go`, `internal/cli/normalize.go`, `internal/config`, and
|
||||
`internal/cli/*_test.go`.
|
||||
- Acceptance criteria: every documented flag, default, and required/mutually
|
||||
exclusive rule matches code; package internals are linked rather than
|
||||
explained in depth.
|
||||
|
||||
### `docs/config.md`
|
||||
|
||||
- Audience: administrators, operators, and advanced users.
|
||||
- Purpose: canonical runtime configuration reference.
|
||||
- Canonical scope: environment variables, default module lists, output schema
|
||||
selection, `speakers.yml`, `autocorrect.yml`, path validation, and precedence.
|
||||
- Recommended outline: config surfaces; output schema precedence; merge module
|
||||
defaults; environment variables; speaker map YAML; autocorrect YAML; path and
|
||||
validation rules; links to examples.
|
||||
- Source of truth: `internal/config/config.go`, `internal/speaker/map.go`,
|
||||
`internal/autocorrect/autocorrect.go`, `internal/config/config_test.go`,
|
||||
`internal/speaker/map_test.go`, and `internal/autocorrect/autocorrect_test.go`.
|
||||
- Acceptance criteria: all config fields and `SERIATIM_*` env vars match code;
|
||||
unsupported config files or unimplemented formats are not described.
|
||||
|
||||
### `docs/operations.md`
|
||||
|
||||
- Audience: administrators and operators.
|
||||
- Purpose: operational behavior for running commands safely.
|
||||
- Canonical scope: file workflow, filesystem layout expectations, output and
|
||||
report files, retry behavior, cleanup, validation failures, and operational
|
||||
caveats.
|
||||
- Recommended outline: normal workflow; input/output/report files; no durable
|
||||
state; failure and retry behavior; reports and diagnostics; cleanup; privacy
|
||||
considerations for transcript artifacts.
|
||||
- Source of truth: `cmd/seriatim/main.go`, `internal/cli`, `internal/config`,
|
||||
`internal/report`, `internal/builtin/output.go`, `internal/normalize`, and
|
||||
trim/merge/normalize CLI tests.
|
||||
- Acceptance criteria: clearly states there is no daemon, database, resume
|
||||
state, remote storage, or background job state; does not invent recovery
|
||||
workflows.
|
||||
|
||||
### `docs/policy/development.md`
|
||||
|
||||
- Audience: developers and coding agents.
|
||||
- Purpose: contributor workflow and change guidance.
|
||||
- Canonical scope: repository layout, build/test commands, coding conventions,
|
||||
dependency policy, adding flags/config fields/modules/docs/examples.
|
||||
- Recommended outline: repo layout; local checks; coding conventions; adding
|
||||
CLI flags; adding config/env vars; adding modules/stages; schema changes;
|
||||
examples and documentation updates.
|
||||
- Source of truth: `docs/policy/documentation.md`,
|
||||
`docs/policy/architecture.md`, `go.mod`, package layout, and test layout.
|
||||
- Acceptance criteria: includes `go test ./...`; states there is no current
|
||||
Makefile, taskfile, linter config, or automated doc checker; aligns with the
|
||||
architecture policy.
|
||||
|
||||
### `docs/internal/pipeline.md`
|
||||
|
||||
- Audience: developers and coding agents.
|
||||
- Purpose: implemented merge pipeline internals.
|
||||
- Canonical scope: registry, stage interfaces, preprocessing state transitions,
|
||||
module order, report event accumulation, final output/report writing.
|
||||
- Recommended outline: purpose; inputs and outputs; stage contracts; registry
|
||||
resolution; execution order; config fields used; adapters; failure behavior;
|
||||
tests; invariants.
|
||||
- Source of truth: `internal/pipeline`, `internal/builtin`, `internal/model`,
|
||||
`internal/report`, `internal/pipeline/runner_test.go`,
|
||||
`internal/builtin/*_test.go`, and `internal/cli/merge_test.go`.
|
||||
- Acceptance criteria: describes only implemented sequential execution; does
|
||||
not document concurrency, plugins, or future formats.
|
||||
|
||||
### `docs/internal/artifacts.md`
|
||||
|
||||
- Audience: developers and coding agents.
|
||||
- Purpose: public artifact conversion and validation internals.
|
||||
- Canonical scope: schema structs, embedded JSON Schemas, conversion from merged
|
||||
model, trim/normalize artifact handling, and output validation.
|
||||
- Recommended outline: artifact contracts; schema selection; conversion;
|
||||
validation; trim projection; normalize canonicalization; tests; invariants.
|
||||
- Source of truth: `schema`, `internal/artifact`, `internal/trim`,
|
||||
`internal/normalize`, and related tests.
|
||||
- Acceptance criteria: links to `schema/*.schema.json`; does not duplicate full
|
||||
schemas or describe unavailable output formats.
|
||||
|
||||
### `docs/internal/modules.md`
|
||||
|
||||
- Audience: developers and coding agents.
|
||||
- Purpose: implemented built-in module behavior and boundaries.
|
||||
- Canonical scope: `json-files`, preprocessing modules, chronological merge,
|
||||
postprocessing modules, and JSON output writer.
|
||||
- Recommended outline: module list; inputs/outputs; config fields used; allowed
|
||||
side effects; ordering constraints; failure behavior; tests; invariants.
|
||||
- Source of truth: `internal/builtin`, `internal/overlap`, `internal/coalesce`,
|
||||
`internal/danglers`, `internal/backchannel`, `internal/filler`,
|
||||
`internal/autocorrect`, and package tests.
|
||||
- Acceptance criteria: avoids full CLI/config duplication; identifies
|
||||
order-sensitive transforms that must run before `assign-ids`.
|
||||
|
||||
### `docs/troubleshooting.md`
|
||||
|
||||
- Audience: users, administrators, and operators.
|
||||
- Purpose: common failure symptoms and safe fixes.
|
||||
- Canonical scope: implemented validation and runtime failures observed in
|
||||
error paths and tests.
|
||||
- Recommended outline: invalid JSON/input shape; missing required flags; invalid
|
||||
output parent directory; invalid speaker/autocorrect YAML; unknown module;
|
||||
invalid output schema; invalid trim selector; schema validation failure;
|
||||
report write failure.
|
||||
- Source of truth: `internal/config`, `internal/cli/*_test.go`,
|
||||
`internal/trim/*_test.go`, `internal/normalize/*_test.go`,
|
||||
`internal/speaker/*_test.go`, and `internal/autocorrect/*_test.go`.
|
||||
- Acceptance criteria: each entry has symptom, likely cause, inspection step,
|
||||
safe fix, and link; no speculative failure modes.
|
||||
|
||||
### `docs/integrations/whisperx-json.md`
|
||||
|
||||
- Audience: developers and coding agents.
|
||||
- Purpose: external input JSON contract used by `merge`.
|
||||
- Canonical scope: the supported WhisperX-like subset only.
|
||||
- Recommended outline: top-level shape; required segment fields; optional word
|
||||
timing fields; validation/failure behavior; how word timing affects overlap
|
||||
resolution; links to CLI and examples.
|
||||
- Source of truth: `internal/builtin/input.go`, merge CLI tests, and README
|
||||
input-format material.
|
||||
- Acceptance criteria: does not attempt to document full WhisperX behavior or
|
||||
unsupported input formats.
|
||||
|
||||
### `docs/integrations/output-schemas.md`
|
||||
|
||||
- Audience: developers, coding agents, and artifact consumers.
|
||||
- Purpose: orientation to public JSON output contracts.
|
||||
- Canonical scope: minimal/intermediate/full schema roles and links to schema
|
||||
files.
|
||||
- Recommended outline: schema selection; minimal; intermediate; full; semantic
|
||||
invariants; validation APIs; links to `schema/*.schema.json`.
|
||||
- Source of truth: `schema/output.go`, `schema/*.schema.json`,
|
||||
`schema/output_test.go`, and `internal/artifact`.
|
||||
- Acceptance criteria: links to machine-readable schemas instead of copying
|
||||
them in full.
|
||||
|
||||
### `examples/`
|
||||
|
||||
- Audience: users, administrators, operators, developers, and coding agents.
|
||||
- Purpose: maintained copyable examples.
|
||||
- Canonical scope: small synthetic inputs and config files for implemented
|
||||
commands only.
|
||||
- Source of truth: examples created during the documentation migration and
|
||||
validated through actual command invocations.
|
||||
- Acceptance criteria: examples are valid, free of secrets/private transcript
|
||||
data, and linked from README, CLI, config, and operations docs.
|
||||
|
||||
## File-by-File Rewrite Guidance
|
||||
|
||||
### README
|
||||
|
||||
Cover what seriatim is, the shortest useful `merge` command, a brief command
|
||||
summary, and links to canonical docs. Avoid full flag tables, config/env
|
||||
reference, module internals, schema examples, troubleshooting details, future
|
||||
formats, or release-history narrative. Inspect `internal/cli`, `internal/config`,
|
||||
and CLI tests before updating commands.
|
||||
|
||||
### CLI Reference
|
||||
|
||||
Document actual `merge`, `trim`, and `normalize` flags from `internal/cli`.
|
||||
Include required flags, defaults, mutually exclusive selector rules, schema
|
||||
selection, report flags, and common workflows. Link to `docs/config.md` for
|
||||
environment variables and YAML formats. Avoid internal package explanations.
|
||||
Inspect `internal/cli/*_test.go` for edge cases and examples.
|
||||
|
||||
### Config Reference
|
||||
|
||||
Document all implemented config surfaces: flags that become config values,
|
||||
`SERIATIM_OUTPUT_SCHEMA`, `SERIATIM_OVERLAP_WORD_RUN_GAP`,
|
||||
`SERIATIM_OVERLAP_WORD_RUN_REORDER_WINDOW`,
|
||||
`SERIATIM_BACKCHANNEL_MAX_DURATION`, `SERIATIM_FILLER_MAX_DURATION`, module
|
||||
lists, output schemas, `speakers.yml`, and `autocorrect.yml`. Avoid command
|
||||
tutorials and unimplemented config files. Inspect `internal/config`,
|
||||
`internal/speaker`, `internal/autocorrect`, and tests.
|
||||
|
||||
### Operations
|
||||
|
||||
Document filesystem-only command execution, output/report artifacts, validation
|
||||
failures, retry behavior, and cleanup. Explicitly say there is no daemon,
|
||||
database, remote storage, resume state, or background job state. Avoid
|
||||
unimplemented recovery procedures.
|
||||
|
||||
### Development Policy
|
||||
|
||||
Document repository layout, `go test ./...`, package conventions,
|
||||
standard-library-first dependency guidance, how to add flags/config/modules,
|
||||
and documentation update expectations. State that no Makefile, taskfile,
|
||||
linter config, or automated documentation checker currently exists.
|
||||
|
||||
### Internal Docs
|
||||
|
||||
Keep internal docs behavior-level and concise. Describe implemented inputs,
|
||||
outputs, boundaries, config fields used, adapters, failure behavior, tests, and
|
||||
invariants. Avoid future plugins, future input/output formats, concurrency, or
|
||||
duplicating CLI/config reference material.
|
||||
|
||||
### Root `architecture.md`
|
||||
|
||||
Do not carry forward future input methods, future formats, future output
|
||||
formats, LLM text, dynamic plugin speculation, or interface sketches that
|
||||
diverge from code. Salvage only current-behavior details that are not already
|
||||
covered in `docs/policy/architecture.md` and move any legitimate future ideas
|
||||
under `docs/roadmap/`.
|
||||
|
||||
## Examples Plan
|
||||
|
||||
Create small synthetic examples under `examples/` rather than relying on the
|
||||
current large `samples/raw` data.
|
||||
|
||||
- `examples/minimal-merge/`
|
||||
- Purpose: shortest complete merge workflow with two small raw JSON files and
|
||||
optional `speakers.yml`.
|
||||
- Expected validity check: run `go run ./cmd/seriatim merge` with the example
|
||||
files and validate JSON output is produced.
|
||||
- Docs to link: README, `docs/cli.md`, `docs/config.md`,
|
||||
`docs/operations.md`.
|
||||
- `examples/normalize/`
|
||||
- Purpose: normalize object-with-`segments` and bare segment array inputs.
|
||||
- Expected validity check: run `go run ./cmd/seriatim normalize` for both
|
||||
shapes.
|
||||
- Docs to link: `docs/cli.md`, `docs/operations.md`, and any Audita/bare
|
||||
array integration note if created.
|
||||
- `examples/trim/`
|
||||
- Purpose: trim a small existing seriatim artifact by `--keep` and/or
|
||||
`--remove`.
|
||||
- Expected validity check: run `go run ./cmd/seriatim trim` and validate
|
||||
sequential retained IDs.
|
||||
- Docs to link: `docs/cli.md`, `docs/operations.md`.
|
||||
- `examples/speakers.yml` and `examples/autocorrect.yml`
|
||||
- Purpose: copyable YAML rule examples if linked from `docs/config.md`.
|
||||
- Expected validity check: load through merge command or package tests.
|
||||
- Docs to link: `docs/config.md`, `docs/cli.md`.
|
||||
|
||||
Do not invent examples for unimplemented input methods, output formats,
|
||||
services, or plugin systems. Do not reuse `samples/raw` as public examples
|
||||
without privacy and size review.
|
||||
|
||||
## Internal Documentation Plan
|
||||
|
||||
### Pipeline
|
||||
|
||||
- Path: `docs/internal/pipeline.md`
|
||||
- Purpose: document implemented merge pipeline orchestration.
|
||||
- Inputs and outputs: `config.Config`, raw transcripts, canonical transcripts,
|
||||
merged transcript, selected public artifact, optional report.
|
||||
- Boundaries: registry and runner orchestration; no CLI flag parsing; no schema
|
||||
details beyond output selection.
|
||||
- Config fields used: input reader, module lists, output modules, output schema,
|
||||
input/output/report files, timing thresholds passed through modules.
|
||||
- Adapters used: input reader, output writer, report writer.
|
||||
- Failure behavior: unknown modules, invalid preprocessing state, stage errors,
|
||||
output/report write failures.
|
||||
- Tests to inspect: `internal/pipeline/runner_test.go`,
|
||||
`internal/builtin/*_test.go`, `internal/cli/merge_test.go`.
|
||||
- Architectural invariants: deterministic sequential stage order, explicit
|
||||
raw-to-canonical preprocessing state, output validation before acceptance.
|
||||
|
||||
### Artifacts and Schemas
|
||||
|
||||
- Path: `docs/internal/artifacts.md`
|
||||
- Purpose: document public artifact conversion and validation internals.
|
||||
- Inputs and outputs: merged model, schema structs, serialized JSON artifacts,
|
||||
parsed trim/normalize artifacts.
|
||||
- Boundaries: conversion and validation only; CLI docs own user-facing flags.
|
||||
- Config fields used: output schema, output modules, input files for metadata.
|
||||
- Adapters used: embedded JSON Schema files and JSON encoders/decoders.
|
||||
- Failure behavior: schema validation errors, unsupported artifact/schema
|
||||
conversion, invalid IDs/timing.
|
||||
- Tests to inspect: `schema/output_test.go`,
|
||||
`internal/artifact/transcript_test.go`, `internal/trim/*_test.go`,
|
||||
`internal/normalize/*_test.go`.
|
||||
- Architectural invariants: sequential IDs, selected schema validation, no
|
||||
internal-only fields in public schemas.
|
||||
|
||||
### Built-In Modules
|
||||
|
||||
- Path: `docs/internal/modules.md`
|
||||
- Purpose: document implemented module responsibilities and ordering
|
||||
constraints.
|
||||
- Inputs and outputs: raw transcripts, preprocess state, merged transcript,
|
||||
report events, selected JSON output.
|
||||
- Boundaries: module behavior only; no full CLI/config reference.
|
||||
- Config fields used: speaker file, autocorrect file, coalesce gap, overlap word
|
||||
gap, word run reorder window, backchannel/filler max durations.
|
||||
- Adapters used: JSON input/output, speaker YAML, autocorrect YAML, report
|
||||
events.
|
||||
- Failure behavior: input validation errors, invalid YAML, unknown module names,
|
||||
invalid output schema before write.
|
||||
- Tests to inspect: `internal/builtin`, `internal/overlap`,
|
||||
`internal/coalesce`, `internal/danglers`, `internal/backchannel`,
|
||||
`internal/filler`, `internal/autocorrect`, and CLI merge tests.
|
||||
- Architectural invariants: order-sensitive transforms run before `assign-ids`;
|
||||
modules stay narrow and explicitly configured.
|
||||
|
||||
### Trim
|
||||
|
||||
- Path: include in `docs/internal/artifacts.md` or create
|
||||
`docs/internal/trim.md` if artifacts doc grows too large.
|
||||
- Purpose: document artifact-level segment projection.
|
||||
- Inputs and outputs: existing seriatim artifact, selector, selected output
|
||||
schema, optional report.
|
||||
- Boundaries: no merge postprocessors; no raw WhisperX input.
|
||||
- Config fields used: input/output/report files, keep/remove selector,
|
||||
optional output schema, allow-empty.
|
||||
- Adapters used: file I/O in CLI, artifact parsing/validation, report writer.
|
||||
- Failure behavior: malformed selector, invalid artifact, missing selected IDs,
|
||||
non-sequential input IDs, empty output unless allowed, unsupported schema
|
||||
up-conversion.
|
||||
- Tests to inspect: `internal/trim/*_test.go`, `internal/cli/trim_test.go`.
|
||||
- Architectural invariants: preserve transcript order, renumber retained IDs,
|
||||
recompute full-schema overlap groups, never run merge modules.
|
||||
|
||||
### Normalize
|
||||
|
||||
- Path: include in `docs/internal/artifacts.md` or create
|
||||
`docs/internal/normalize.md` if artifacts doc grows too large.
|
||||
- Purpose: document artifact-level transcript canonicalization.
|
||||
- Inputs and outputs: transcript-like JSON object or bare array, selected
|
||||
seriatim output schema, optional report.
|
||||
- Boundaries: no merge preprocessing or postprocessing modules.
|
||||
- Config fields used: input/output/report files, output schema, output modules.
|
||||
- Adapters used: file I/O, JSON parsing, schema validation, report writer.
|
||||
- Failure behavior: invalid JSON, unsupported top-level shape, invalid timing
|
||||
after repair, unsupported output module/schema, report write failure.
|
||||
- Tests to inspect: `internal/normalize/*_test.go`,
|
||||
`internal/cli/normalize_test.go`.
|
||||
- Architectural invariants: deterministic repair/sort/ID assignment, no
|
||||
transcript text in normalize report events, no merge modules.
|
||||
|
||||
## Integration Documentation Plan
|
||||
|
||||
- `docs/integrations/whisperx-json.md`
|
||||
- External system or contract: WhisperX-like JSON transcript subset.
|
||||
- Current usage: `merge` reads a top-level `segments` array with required
|
||||
segment timing/text and optional word timing.
|
||||
- Version or compatibility notes: no explicit WhisperX version is encoded in
|
||||
the repository; document only the accepted subset.
|
||||
- Document: supported fields, validation, word timing behavior, errors.
|
||||
- Do not document: full WhisperX schema, audio diarization, non-JSON formats.
|
||||
- `docs/integrations/output-schemas.md`
|
||||
- External system or contract: seriatim public JSON output contracts.
|
||||
- Current usage: `merge`, `trim`, and `normalize` emit
|
||||
`seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`.
|
||||
- Version or compatibility notes: schemas are embedded from `schema/`; release
|
||||
version metadata is injected through build info.
|
||||
- Document: schema roles, semantic invariants, validation APIs, links to
|
||||
schema files.
|
||||
- Do not document: unimplemented output formats or full schema copies.
|
||||
- YAML rule files
|
||||
- Prefer documenting speaker and autocorrect YAML contracts in
|
||||
`docs/config.md`. Create `docs/integrations/yaml-rule-files.md` only if the
|
||||
config reference becomes too large.
|
||||
- Audita-style bare arrays
|
||||
- Cover under `docs/cli.md` normalize behavior unless maintainers need a
|
||||
separate integration note. Do not generalize beyond implemented bare segment
|
||||
arrays.
|
||||
- No external CLI/API/service docs are needed now. The repository implements no
|
||||
external CLI, network API, daemon, remote storage, or service integration.
|
||||
|
||||
## Recommended Implementation Sequence
|
||||
|
||||
### Stage 1: Write Documentation Roadmap
|
||||
|
||||
- Goal: create this roadmap.
|
||||
- Files: `docs/roadmap/documentation.md`.
|
||||
- Repository areas to inspect: documentation policy, architecture policy,
|
||||
README, root `architecture.md`, CLI/config/pipeline/schema/report/tests.
|
||||
- Acceptance criteria: roadmap exists, no other files changed by this stage,
|
||||
and the roadmap is action-oriented.
|
||||
- Suggested validation commands: `go test ./...`; `git status --short`.
|
||||
- Prompt size: one implementation prompt.
|
||||
|
||||
### Stage 2: User-Facing Canonical Docs and Slim README
|
||||
|
||||
- Goal: move user reference material out of README into canonical docs.
|
||||
- Files: update `README.md`; create `docs/cli.md` and `docs/config.md`.
|
||||
- Repository areas to inspect: `internal/cli`, `internal/config`,
|
||||
`internal/speaker`, `internal/autocorrect`, CLI/config tests.
|
||||
- Acceptance criteria: README is concise; CLI/config docs match flags, defaults,
|
||||
env vars, YAML formats, and validation; no roadmap-only content appears.
|
||||
- Suggested validation commands: `go test ./...`;
|
||||
`go run ./cmd/seriatim --help`;
|
||||
`go run ./cmd/seriatim merge --help`;
|
||||
`go run ./cmd/seriatim trim --help`;
|
||||
`go run ./cmd/seriatim normalize --help`;
|
||||
stale-term grep from the validation plan.
|
||||
- Prompt size: one prompt if concise; split if README rewrite or config
|
||||
reference grows too large.
|
||||
|
||||
### Stage 3: Operations and Troubleshooting
|
||||
|
||||
- Goal: document runtime operation, reports, failure behavior, and common fixes.
|
||||
- Files: create `docs/operations.md` and `docs/troubleshooting.md`.
|
||||
- Repository areas to inspect: `cmd/seriatim/main.go`, `internal/cli`,
|
||||
`internal/config`, `internal/report`, output writer, normalize/trim/merge
|
||||
tests.
|
||||
- Acceptance criteria: docs describe filesystem-only operation and current
|
||||
failure modes; no daemon, resume, remote storage, or recovery behavior is
|
||||
invented.
|
||||
- Suggested validation commands: `go test ./...`; manual link review.
|
||||
- Prompt size: one prompt.
|
||||
|
||||
### Stage 4: Developer and Internal Docs
|
||||
|
||||
- Goal: create developer workflow and implemented internal component docs.
|
||||
- Files: create `docs/policy/development.md`,
|
||||
`docs/internal/pipeline.md`, `docs/internal/artifacts.md`, and
|
||||
`docs/internal/modules.md`.
|
||||
- Repository areas to inspect: architecture policy, pipeline, modules, schema,
|
||||
artifact conversion, trim/normalize packages, tests.
|
||||
- Acceptance criteria: docs preserve boundaries, avoid CLI/config duplication,
|
||||
and identify tests/invariants for future changes.
|
||||
- Suggested validation commands: `go test ./...`; grep for unimplemented
|
||||
future-format/plugin/concurrency claims outside roadmap.
|
||||
- Prompt size: split into development policy and internal docs if needed.
|
||||
|
||||
### Stage 5: Integrations and Examples
|
||||
|
||||
- Goal: add concise integration notes and maintained synthetic examples.
|
||||
- Files: create `docs/integrations/whisperx-json.md`,
|
||||
`docs/integrations/output-schemas.md`, and `examples/*`; decide whether
|
||||
`samples/` should remain separate.
|
||||
- Repository areas to inspect: `internal/builtin/input.go`, `schema`,
|
||||
`internal/artifact`, CLI tests, existing `samples/`.
|
||||
- Acceptance criteria: examples are small, synthetic, valid, and linked from
|
||||
relevant docs; integration docs document only implemented contracts.
|
||||
- Suggested validation commands: `go test ./...`; run documented example
|
||||
`go run` commands; validate example YAML through command paths.
|
||||
- Prompt size: split if examples need tests or sample cleanup decisions.
|
||||
|
||||
### Stage 6: Stale Documentation Cleanup
|
||||
|
||||
- Goal: remove wrong-home and stale documentation after canonical replacements
|
||||
exist.
|
||||
- Files: delete or relocate root `architecture.md`; remove stale material from
|
||||
README; update links across docs.
|
||||
- Repository areas to inspect: all docs, README, roadmap, root files.
|
||||
- Acceptance criteria: no links to deleted root `architecture.md`; no
|
||||
unimplemented behavior outside `docs/roadmap/`; canonical homes are respected.
|
||||
- Suggested validation commands: `go test ./...`; stale-term grep; manual link
|
||||
check; `git status --short`.
|
||||
- Prompt size: one prompt.
|
||||
|
||||
## Validation Plan
|
||||
|
||||
Use these checks during or after documentation migration:
|
||||
|
||||
- Run `go test ./...`.
|
||||
- Run `go run ./cmd/seriatim --help`.
|
||||
- Run `go run ./cmd/seriatim merge --help`.
|
||||
- Run `go run ./cmd/seriatim trim --help`.
|
||||
- Run `go run ./cmd/seriatim normalize --help`.
|
||||
- Once examples exist, run each documented example command and verify output is
|
||||
produced in a temporary path.
|
||||
- Load example YAML through the merge command or package tests.
|
||||
- Validate example JSON through existing CLI/schema paths where practical.
|
||||
- Grep outside `docs/roadmap/` for stale or roadmap-only terms:
|
||||
`Future input`, `Future output`, `LLM`, `plugin`, `SRT`, `VTT`, `.tar.gz`,
|
||||
`URI`, `old format`, `not implemented yet`, and
|
||||
`runtime default may change`.
|
||||
- Manually check links unless a link checker is added. No automated
|
||||
documentation checker currently exists.
|
||||
- Verify docs and examples contain no secrets, private transcript data, API
|
||||
keys, tokens, passwords, or private infrastructure details.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should `samples/` be removed, kept as non-doc sample data, or replaced by
|
||||
small synthetic `examples/`? Recommendation: create small synthetic examples
|
||||
first, then audit `samples/` for privacy, size, and ongoing maintenance before
|
||||
deleting or linking it.
|
||||
- Should Audita-style bare-array normalization have a separate integration doc?
|
||||
Recommendation: cover it in `docs/cli.md` normalize behavior unless a
|
||||
stronger external-contract requirement emerges.
|
||||
Reference in New Issue
Block a user