diagnose-ocr-ci — peachest/skills

Diagnose ocr-review runs by walking the layer ladder — seven layers the run climbs from pod scheduling to artifact upload (CI) or its local subset (config → grouping → per-file). Every failure lives at exactly one layer; the diagnosis is the answer to "which rung did the run stop on, and which signature proves it".

Procedure

Identify the target. One of:
- a GitLab project (survey all its ocr-review jobs) or a specific job ID;
- a local session — ~/.opencodereview/sessions/<project>/<uuid>.jsonl, addressed by uuid prefix or path (local command), or "the ocr run that kept failing today" (list with local, pick the failed entries);
- pasted log/artifact files (analyze). If the user gave none of these, ask.
Fetch evidence with the script (see below). For CI jobs, artifacts (ocr-result.json + ocr-stderr.log) are primary; the trace is the fallback when artifacts are absent. For local sessions, the jsonl is the single source.
Locate the layer. Map the extracted signatures to the ladder. The verdict layer is the deepest layer reached with a failure signature — deeper layers must show no failure signatures, else the diagnosis is incomplete.
Verify against baselines before calling a run abnormal (see Baselines).
Report using the conclusion template. Output is Chinese for the user.

Completion criterion: every signature the script extracted is either explained by the verdict layer or explicitly ruled incidental — an unexplained 504 is an unfinished diagnosis, not noise.

Local sessions

~/.opencodereview/sessions/<munged-cwd>/<uuid>.jsonl records every local ocr review run: session_start (cwd/branch/model/range), llm_request/llm_response (duration_ms + usage), llm_error, tool_call, review_item_failed, session_end (terminal_state + run_manifest, same manifest schema as CI's ocr-result.json). The script's local command classifies every llm_error and infers the effective OCR_LLM_TIMEOUT from the deadline-duration cluster: