Verified:GitHub

diagnose-ocr-ci

Diagnose ocr-review failures across GitLab CI jobs and local sessions using a seven-layer failure ladder.

Updated Jul 20, 2026

Search Tags:#code review #troubleshooting #failure analysis #diagnose #gitlab ci #ci pipeline #llm timeout

One-click install

npx skills add https://github.com/peachest/skills --skill diagnose-ocr-ci-peachest

Or copy as Structured Prompt for Agent▼

Please help me install this Agent Skill.
Skill: diagnose-ocr-ci
Source: https://github.com/peachest/skills/tree/main/in-progress/diagnose-ocr-ci
Command: npx skills add https://github.com/peachest/skills --skill diagnose-ocr-ci-peachest

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, and includes scripts (resource) components.

What problem does it solve? When an ocr-review run fails, hangs, times out, or posts only some inline comments, finding the root cause means digging through CI traces, artifacts, retry reports, and local session logs by hand. This Skill automates that investigation by mapping every failure signature to exactly one layer of a seven-layer ladder, from pod scheduling to artifact upload. ## Core Features & Use Cases - Layer-ladder diagnosis: Classifies failures into seven layers (pod scheduling, before_script, ocr config, grouping, per-file tasks, comment posting, artifact upload) using signature matching on traces, ocr-result.json, and retry reports. - Group and project surveys: Scans all ocr-review jobs across GitLab groups on multiple instances with cross-group dedup, failure-mode clustering by duration signature, and per-day loss distribution. - Local session analysis: Parses ~/.opencodereview/sessions jsonl files to classify llm_error types (gateway hang, slow request cut, stream break), infer the effective OCR_LLM_TIMEOUT, and compare token throughput against baselines. - Speed-shift attribution: Tracks daily duration medians of successful jobs and attributes speed changes to config merges, image bumps, or gateway recovery via before/after splits. - Use Case: A user notices an ocr-review job posted only 3 of 8 comments and asks why. The Skill fetches the job artifacts, finds the per-file timeout signature at layer 5, and reports the root cause with the exact env var to adjust. ## Quick Start Ask the agent to diagnose why the ocr-review job failed on the internal GitLab project, or to analyze the local ocr session that kept failing today.

Frequently Asked Questions about diagnose-ocr-ci

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I diagnose a failed ocr-review GitLab CI job?▼

Run the diagnose script with the project path and job ID. It fetches artifacts first (ocr-result.json and ocr-stderr.log), falls back to the job trace when artifacts are absent, and maps failure signatures to one of seven layers to identify the root cause.

How to find out why ocr-review posted only some inline comments?▼

Check the layer 6 signature comparing posted N/M counts in the job output. A partial N/M posting means the MR moved, permissions changed, or comment positions became invalid, while N/N confirms all comments posted successfully.

Can I analyze local ocr review sessions that keep failing?▼

Yes, local sessions are stored as jsonl files under ~/.opencodereview/sessions. The local command lists recent sessions with failures first, classifies every llm_error, and infers the effective OCR_LLM_TIMEOUT from deadline-duration clusters.

Why does a retried GitLab job still run the old CI config?▼

A retried job does not re-resolve include directives, so if the pipeline was created before the common-ci config fix merged, the retry runs the frozen old config. The fix is pushing a new commit to trigger a fresh pipeline, never a retry.

What does a 504 with duration matching the timeout mean in retry reports?▼

A 504 status where duration_to_headers_ms approximately equals OCR_LLM_TIMEOUT times 1000 indicates a gateway hang: the request waited the full timeout before the gateway cut it. This is a gateway-side problem, not a client-side one.

What are the limitations of group-level ocr-review surveys?▼

Group surveys cap at 100 jobs per project, so trend counts are a lower bound. Group IDs are not unique across GitLab instances, and projects shared across groups require cross-group dedup to avoid double-counting failures.