From 546be2ab92514e67add8ad2f1aa822c2a3eafd92 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 24 May 2026 09:33:51 -0500 Subject: [PATCH] Remove the completed documentation roadmap --- docs/roadmap/documentation.md | 586 ---------------------------------- 1 file changed, 586 deletions(-) delete mode 100644 docs/roadmap/documentation.md diff --git a/docs/roadmap/documentation.md b/docs/roadmap/documentation.md deleted file mode 100644 index e891c50..0000000 --- a/docs/roadmap/documentation.md +++ /dev/null @@ -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.