Add operations and troubleshooting documentation
This commit is contained in:
@@ -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:
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
132
docs/operations.md
Normal file
132
docs/operations.md
Normal file
@@ -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)
|
||||
102
docs/troubleshooting.md
Normal file
102
docs/troubleshooting.md
Normal file
@@ -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 <path>`
|
||||
- `ls -ld <parent-dir>`
|
||||
- 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 . <input-file>`
|
||||
- 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' <input-file>`
|
||||
- `jq 'keys' <input-file>` (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 <report-parent-dir>`
|
||||
- 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)
|
||||
Reference in New Issue
Block a user