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

Rewrite troubleshooting docs for current render and artifact behavior

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-24 23:03:19 +00:00
parent da3720693d
commit 0dfd06c349
1 changed files with 40 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/troubleshooting.md
View File

@@ -4,30 +4,31 @@ Each entry includes symptom, likely cause, inspection step, and safe fix.
## Missing required flags ## 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`. - Symptom: command fails with messages like `--input-file is required`, `--output-file is required`, `--format is required`, or `exactly one of --keep or --remove is required`.
- Likely cause: required command flags were omitted. - Likely cause: one or more required flags were omitted.
- Inspection: run command help for the failing command: - Inspection: run help for the failing command:
- `go run ./cmd/seriatim merge --help` - `go run ./cmd/seriatim merge --help`
- `go run ./cmd/seriatim trim --help` - `go run ./cmd/seriatim trim --help`
- `go run ./cmd/seriatim normalize --help` - `go run ./cmd/seriatim normalize --help`
- `go run ./cmd/seriatim render --help`
- Safe fix: provide all required flags; for `trim`, provide exactly one selector mode (`--keep` or `--remove`). - Safe fix: provide all required flags; for `trim`, provide exactly one selector mode (`--keep` or `--remove`).
## Invalid output or report path ## Invalid output or report path
- Symptom: errors like `--output-file parent directory ...` or `--report-file parent directory ...`. - 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. - Likely cause: parent directory does not exist, is not a directory, or the target path is unusable.
- Inspection: verify paths: - Inspection: verify parent path and permissions:
- `dirname <path>` - `dirname <path>`
- `ls -ld <parent-dir>` - `ls -ld <parent-dir>`
- Safe fix: create/fix the parent directory and rerun; avoid using directory paths directly as output/report file targets. - Safe fix: create or fix the parent directory and rerun. Use a file path (not a directory path) for output/report targets.
## Invalid merge input JSON ## 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`. - 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. - Likely cause: malformed JSON or unsupported/missing fields in a merge input file.
- Inspection: validate input JSON and required fields (`start`, `end`, `text`): - Inspection: validate JSON and required segment fields (`start`, `end`, `text`):
- `jq . <input-file>` - `jq . <input-file>`
- Safe fix: correct the JSON structure and segment/word field types, then rerun `merge`. - Safe fix: correct JSON structure and segment/word field types, then rerun `merge`.
## Invalid normalize input shape ## Invalid normalize input shape
@@ -38,13 +39,22 @@ Each entry includes symptom, likely cause, inspection step, and safe fix.
- `jq 'keys' <input-file>` (for object input) - `jq 'keys' <input-file>` (for object input)
- Safe fix: reshape input into one supported form and rerun `normalize`. - Safe fix: reshape input into one supported form and rerun `normalize`.
## Invalid render input artifact
- Symptom: render fails with messages like `input JSON is malformed` or `input JSON is not a valid seriatim output artifact`.
- Likely cause: input is malformed JSON or not one of the supported seriatim output schemas.
- Inspection:
- `jq . <input-file>`
- compare input shape against `schema/minimal-output.schema.json`, `schema/intermediate-output.schema.json`, and `schema/full-output.schema.json`
- Safe fix: render only a valid existing seriatim artifact (`seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`).
## Invalid speaker map or autocorrect YAML ## 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. - 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. - Likely cause: YAML rule file structure/content does not match expected contract.
- Inspection: check YAML validity and required top-level keys: - Inspection: check YAML validity and required top-level keys:
- `speakers.yml` requires top-level `match` rules. - `speakers.yml` requires top-level `match` rules
- `autocorrect.yml` requires top-level `autocorrect` rules. - `autocorrect.yml` requires top-level `autocorrect` rules
- Safe fix: correct YAML structure and rule content, then rerun `merge`. - Safe fix: correct YAML structure and rule content, then rerun `merge`.
## Unknown module names ## Unknown module names
@@ -54,14 +64,18 @@ Each entry includes symptom, likely cause, inspection step, and safe fix.
- Inspection: compare provided module names against defaults in CLI help and config docs. - 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. - Safe fix: use implemented module names only or remove unsupported modules from comma-separated lists.
## Invalid output schema value ## Invalid format or schema values
- Symptom: errors like `--output-schema must be one of ...`. - Symptom:
- Likely cause: unsupported schema value from flag or `SERIATIM_OUTPUT_SCHEMA`. - render: `--format must be "markdown"`
- Inspection: check effective value: - merge/normalize/trim: `--output-schema must be one of ...`
- Likely cause: unsupported `--format` or `--output-schema` value.
- Inspection:
- command flags - command flags
- `echo "$SERIATIM_OUTPUT_SCHEMA"` - `echo "$SERIATIM_OUTPUT_SCHEMA"` (for merge/normalize defaults)
- Safe fix: use one of `seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`. - Safe fix:
- render: use `--format markdown`
- output schema: use `seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`
## Invalid trim selector ## Invalid trim selector
@@ -73,23 +87,23 @@ Each entry includes symptom, likely cause, inspection step, and safe fix.
- list: `1-10,15,20-25` - list: `1-10,15,20-25`
- Safe fix: correct selector syntax and rerun `trim`. - Safe fix: correct selector syntax and rerun `trim`.
## Schema validation failures ## Artifact or schema validation failures
- Symptom: errors such as `validate-output: ...` in merge or `input JSON is not a valid seriatim output artifact` in trim. - Symptom: errors such as `validate-output: ...`, `input JSON is not a valid seriatim output artifact`, or related schema-validation errors.
- Likely cause: - Likely cause:
- merge module order/config produced invalid final artifact (for example, validating before IDs are assigned), or - merge module order/config produced an invalid output artifact, or
- trim input is not a valid seriatim artifact. - trim/render input is not a valid seriatim output artifact.
- Inspection: - Inspection:
- for merge: inspect customized module ordering flags. - for merge: inspect customized module ordering flags
- for trim: verify input artifact against known seriatim schema files in `schema/`. - for trim/render: validate input against schema files in `schema/`
- Safe fix: - Safe fix:
- restore valid merge postprocessing order ending with assigned IDs before validation, or - merge: restore a valid postprocessing order ending with assigned IDs before output validation
- provide a valid seriatim artifact as trim input. - trim/render: provide a valid seriatim artifact as input
## Report write failure ## Report write failure
- Symptom: errors like `write --report-file ...` or file-create failures when report writing is requested. - 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). - Likely cause: report path is not writable or points to an invalid target.
- Inspection: - Inspection:
- `ls -ld <report-parent-dir>` - `ls -ld <report-parent-dir>`
- verify `--report-file` is a file path, not a directory - verify `--report-file` is a file path, not a directory