eric/seriatim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Remove the completed documentation roadmap

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-24 09:33:51 -05:00
parent 7743b397a6
commit 546be2ab92
1 changed files with 0 additions and 586 deletions
Download Patch File Download Diff File Expand all files Collapse all files

586
docs/roadmap/documentation.md
View File

@@ -1,586 +0,0 @@
# 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: review and finalize this roadmap as the implementation plan for the
documentation migration.
- Files: `docs/roadmap/documentation.md` only.
- Repository areas inspected: documentation policy, architecture policy,
`README.md`, root `architecture.md`, and CLI/config/pipeline/schema/report
code and tests.
- Completion status: complete (2026-05-24).
- Completion evidence:
- `go test ./...` passed.
- `git status --short` confirmed no unrelated working-tree changes before
roadmap-only edits.
- Acceptance criteria: roadmap is present, action-oriented, and constrained to
implemented behavior outside `docs/roadmap/`.
- 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.