From b3e7dc3136beada3e56f2d15ada218624bcd2bbc Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 24 May 2026 13:34:51 +0000 Subject: [PATCH] Add operations and troubleshooting documentation --- README.md | 2 + docs/cli.md | 4 +- docs/config.md | 4 +- docs/operations.md | 132 ++++++++++++++++++++++++++++++++++++++++ docs/troubleshooting.md | 102 +++++++++++++++++++++++++++++++ 5 files changed, 242 insertions(+), 2 deletions(-) create mode 100644 docs/operations.md create mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md index bf839ed..b8b6043 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,8 @@ go run ./cmd/seriatim merge \ - CLI reference: [docs/cli.md](docs/cli.md) - Configuration reference: [docs/config.md](docs/config.md) +- Operations guide: [docs/operations.md](docs/operations.md) +- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md) - Development architecture policy: [docs/policy/architecture.md](docs/policy/architecture.md) - Documentation policy: [docs/policy/documentation.md](docs/policy/documentation.md) - Public JSON schemas: diff --git a/docs/cli.md b/docs/cli.md index 37cbf46..df1a1dc 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -169,8 +169,10 @@ go run ./cmd/seriatim normalize \ ## Related docs - Configuration reference: [config.md](config.md) +- Operations guide: [operations.md](operations.md) +- Troubleshooting: [troubleshooting.md](troubleshooting.md) - Public output schemas: - [../schema/minimal-output.schema.json](../schema/minimal-output.schema.json) - [../schema/intermediate-output.schema.json](../schema/intermediate-output.schema.json) - [../schema/full-output.schema.json](../schema/full-output.schema.json) -- Remaining docs migration work (operations, troubleshooting, examples): [roadmap/documentation.md](roadmap/documentation.md) +- Remaining docs migration work: [roadmap/documentation.md](roadmap/documentation.md) diff --git a/docs/config.md b/docs/config.md index ede1637..d707624 100644 --- a/docs/config.md +++ b/docs/config.md @@ -155,8 +155,10 @@ All commands: ## Related docs - CLI reference: [cli.md](cli.md) +- Operations guide: [operations.md](operations.md) +- Troubleshooting: [troubleshooting.md](troubleshooting.md) - Public output schemas: - [../schema/minimal-output.schema.json](../schema/minimal-output.schema.json) - [../schema/intermediate-output.schema.json](../schema/intermediate-output.schema.json) - [../schema/full-output.schema.json](../schema/full-output.schema.json) -- Remaining docs migration work (operations, troubleshooting, examples): [roadmap/documentation.md](roadmap/documentation.md) +- Remaining docs migration work: [roadmap/documentation.md](roadmap/documentation.md) diff --git a/docs/operations.md b/docs/operations.md new file mode 100644 index 0000000..edf3d6e --- /dev/null +++ b/docs/operations.md @@ -0,0 +1,132 @@ +# Operations Guide + +## Scope + +This document covers runtime operation of the implemented CLI commands: + +- `merge` +- `trim` +- `normalize` + +## Runtime model + +seriatim is a single-process, filesystem-only CLI. + +- Each invocation reads input files, processes in memory, and writes output files. +- There is no daemon, queue, database, resume checkpoint, remote storage, or background worker. +- On error, the command exits non-zero; there is no built-in retry/resume flow. + +## Filesystem expectations + +All commands require accessible local files and existing parent directories for outputs. + +- Input paths must exist and must be files. +- Output/report parent directories must already exist. +- Output and report files are created with `os.Create`, so existing files at those paths are overwritten. + +Command-specific expectations: + +- `merge`: requires at least one `--input-file`; optional `--speakers` and `--autocorrect` paths must exist when provided. +- `trim`: input must be an existing valid seriatim artifact JSON file. +- `normalize`: input must be a JSON object with `segments` or a top-level segment array. + +## Normal workflow + +### Merge + +1. Provide one or more `--input-file` values. +2. Optionally provide `--speakers`, `--autocorrect`, and `--report-file`. +3. Provide `--output-file`. +4. Run command. + +Example: + +```sh +go run ./cmd/seriatim merge \ + --input-file speaker-a.json \ + --input-file speaker-b.json \ + --output-file merged.json \ + --report-file merge-report.json +``` + +### Trim + +1. Provide existing artifact with `--input-file`. +2. Select segments with exactly one of `--keep` or `--remove`. +3. Provide `--output-file`. +4. Optionally provide `--output-schema`, `--allow-empty`, and `--report-file`. + +Example: + +```sh +go run ./cmd/seriatim trim \ + --input-file merged.json \ + --output-file trimmed.json \ + --keep "1-20,25" +``` + +### Normalize + +1. Provide `--input-file` containing supported JSON shape. +2. Provide `--output-file`. +3. Optionally provide `--output-schema`, `--output-modules`, and `--report-file`. + +Example: + +```sh +go run ./cmd/seriatim normalize \ + --input-file external.json \ + --output-file normalized.json \ + --report-file normalize-report.json +``` + +## Output and report artifacts + +Primary output: + +- `--output-file` writes JSON transcript artifact in selected schema. + +Optional report output: + +- `--report-file` writes deterministic JSON report events. +- `merge` report metadata records reader/modules and event sequence. +- `trim` report includes a `trim-audit` event with mode/selector/counts and old-to-new ID mapping. +- `normalize` report includes a `normalize-audit` event with input shape, repair stats, and output selection details. + +## Failure and retry behavior + +Failure behavior: + +- Errors are printed once to stderr by the root command and exit status is `1`. +- There is no partial-state recovery mechanism. + +Retry guidance: + +1. Fix the reported input/config/path issue. +2. Re-run the same command. +3. If a prior run created a partial or unwanted output/report file, remove it and rerun. + +Operational note: + +- With identical inputs/config/version, merge behavior is deterministic and input files are sorted before processing. + +## Cleanup + +seriatim does not manage retention. + +- Remove unneeded output/report artifacts manually. +- No cache, state directory, or lock files are maintained by the application. + +## Privacy considerations + +Transcript artifacts and reports are local files and may contain sensitive conversational data. + +- Store outputs in controlled directories with appropriate OS permissions. +- Share report files carefully; they include file paths and processing diagnostics. +- Normalize report events intentionally avoid embedding transcript text, but output artifacts contain transcript content. + +## Related docs + +- CLI reference: [cli.md](cli.md) +- Configuration reference: [config.md](config.md) +- Troubleshooting: [troubleshooting.md](troubleshooting.md) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..4e6440b --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,102 @@ +# Troubleshooting + +Each entry includes symptom, likely cause, inspection step, and safe fix. + +## Missing required flags + +- Symptom: command fails with messages like `--input-file is required`, `--output-file is required`, or `exactly one of --keep or --remove is required`. +- Likely cause: required command flags were omitted. +- Inspection: run command help for the failing command: + - `go run ./cmd/seriatim merge --help` + - `go run ./cmd/seriatim trim --help` + - `go run ./cmd/seriatim normalize --help` +- Safe fix: provide all required flags; for `trim`, provide exactly one selector mode (`--keep` or `--remove`). + +## Invalid output or report path + +- Symptom: errors like `--output-file parent directory ...` or `--report-file parent directory ...`. +- Likely cause: parent directory does not exist, is not a directory, or path points to an unusable target. +- Inspection: verify paths: + - `dirname ` + - `ls -ld ` +- Safe fix: create/fix the parent directory and rerun; avoid using directory paths directly as output/report file targets. + +## Invalid merge input JSON + +- Symptom: merge fails with messages like `parse input file`, `must contain top-level segments array`, `segment 0 missing numeric start`, or `segment 0 words must be an array`. +- Likely cause: malformed JSON or unsupported/missing fields in a merge input file. +- Inspection: validate input JSON and required fields (`start`, `end`, `text`): + - `jq . ` +- Safe fix: correct the JSON structure and segment/word field types, then rerun `merge`. + +## Invalid normalize input shape + +- Symptom: normalize fails with messages like `must contain a "segments" field`, `"segments" must be an array`, or `top-level object with "segments" or a top-level segment array`. +- Likely cause: normalize input is neither supported object-with-segments nor top-level segment array. +- Inspection: inspect top-level JSON shape: + - `jq 'type' ` + - `jq 'keys' ` (for object input) +- Safe fix: reshape input into one supported form and rerun `normalize`. + +## Invalid speaker map or autocorrect YAML + +- Symptom: merge fails with errors such as `must contain at least one match rule`, `must include speaker`, `must include target`, or duplicate match/speaker validation failures. +- Likely cause: YAML rule file structure/content does not match expected schema. +- Inspection: check YAML validity and required top-level keys: + - `speakers.yml` requires top-level `match` rules. + - `autocorrect.yml` requires top-level `autocorrect` rules. +- Safe fix: correct YAML structure and rule content, then rerun `merge`. + +## Unknown module names + +- Symptom: errors like `unknown input reader`, `unknown preprocessing module`, `unknown postprocessing module`, or `unknown output module`. +- Likely cause: module name typo or unsupported module in flag lists. +- Inspection: compare provided module names against defaults in CLI help and config docs. +- Safe fix: use implemented module names only or remove unsupported modules from comma-separated lists. + +## Invalid output schema value + +- Symptom: errors like `--output-schema must be one of ...`. +- Likely cause: unsupported schema value from flag or `SERIATIM_OUTPUT_SCHEMA`. +- Inspection: check effective value: + - command flags + - `echo "$SERIATIM_OUTPUT_SCHEMA"` +- Safe fix: use one of `seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`. + +## Invalid trim selector + +- Symptom: trim fails with messages like `invalid selector ... malformed element`, `segment ID must be positive`, or descending-range errors. +- Likely cause: selector syntax is invalid. +- Inspection: verify selector format: + - single ID: `7` + - range: `1-10` + - list: `1-10,15,20-25` +- Safe fix: correct selector syntax and rerun `trim`. + +## Schema validation failures + +- Symptom: errors such as `validate-output: ...` in merge or `input JSON is not a valid seriatim output artifact` in trim. +- Likely cause: + - merge module order/config produced invalid final artifact (for example, validating before IDs are assigned), or + - trim input is not a valid seriatim artifact. +- Inspection: + - for merge: inspect customized module ordering flags. + - for trim: verify input artifact against known seriatim schema files in `schema/`. +- Safe fix: + - restore valid merge postprocessing order ending with assigned IDs before validation, or + - provide a valid seriatim artifact as trim input. + +## Report write failure + +- Symptom: errors like `write --report-file ...` or file-create failures when report writing is requested. +- Likely cause: report path is not writable or is an invalid target (for example a directory path). +- Inspection: + - `ls -ld ` + - verify `--report-file` is a file path, not a directory +- Safe fix: choose a writable file path under an existing directory and rerun. + +## Related docs + +- CLI reference: [cli.md](cli.md) +- Configuration reference: [config.md](config.md) +- Operations guide: [operations.md](operations.md)