diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 4e6440b..352496c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -4,30 +4,31 @@ 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: +- 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: one or more required flags were omitted. +- Inspection: run help for the failing command: - `go run ./cmd/seriatim merge --help` - `go run ./cmd/seriatim trim --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`). ## 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: +- Likely cause: parent directory does not exist, is not a directory, or the target path is unusable. +- Inspection: verify parent path and permissions: - `dirname ` - `ls -ld ` -- 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 - 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`): +- Inspection: validate JSON and required segment fields (`start`, `end`, `text`): - `jq . ` -- 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 @@ -38,13 +39,22 @@ Each entry includes symptom, likely cause, inspection step, and safe fix. - `jq 'keys' ` (for object input) - 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 . ` + - 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 - 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: - - `speakers.yml` requires top-level `match` rules. - - `autocorrect.yml` requires top-level `autocorrect` rules. + - `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 @@ -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. - 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 ...`. -- Likely cause: unsupported schema value from flag or `SERIATIM_OUTPUT_SCHEMA`. -- Inspection: check effective value: +- Symptom: + - render: `--format must be "markdown"` + - merge/normalize/trim: `--output-schema must be one of ...` +- Likely cause: unsupported `--format` or `--output-schema` value. +- Inspection: - command flags - - `echo "$SERIATIM_OUTPUT_SCHEMA"` -- Safe fix: use one of `seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`. + - `echo "$SERIATIM_OUTPUT_SCHEMA"` (for merge/normalize defaults) +- Safe fix: + - render: use `--format markdown` + - output schema: use `seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full` ## Invalid trim selector @@ -73,23 +87,23 @@ Each entry includes symptom, likely cause, inspection step, and safe fix. - list: `1-10,15,20-25` - 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: - - merge module order/config produced invalid final artifact (for example, validating before IDs are assigned), or - - trim input is not a valid seriatim artifact. + - merge module order/config produced an invalid output artifact, or + - trim/render input is not a valid seriatim output artifact. - Inspection: - - for merge: inspect customized module ordering flags. - - for trim: verify input artifact against known seriatim schema files in `schema/`. + - for merge: inspect customized module ordering flags + - for trim/render: validate input against 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. + - merge: restore a valid postprocessing order ending with assigned IDs before output validation + - trim/render: provide a valid seriatim artifact as 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). +- Likely cause: report path is not writable or points to an invalid target. - Inspection: - `ls -ld ` - verify `--report-file` is a file path, not a directory