GeezerVison

doc-check reviews are too big and too slow for the local model, and the job result does not match the review result.

From 2026-11-04 to 11-11 (week report):

• 613 review turns. The median completed turn took 67 minutes, and a turn with findings took 247 minutes.
• 489 of 500 failed jobs were the 40-minute wait timing out while the chat still ran. 158 turns ended with no trace.
• A review starts 1 orchestrator, up to 7 persona chats, and 1 verifier per group of findings. The personas load 113.7k tokens of docs/.style pages, but the pages are only 42.4k tokens without repeats.
• One chat is reused for every push, so it keeps growing. A PR got 2.3 turns on average, and one got 18.
• Of 27 PRs with posted findings, 17 were right, 3 mixed, 3 debatable, and 4 wrong. Style nits such as contractions, "often", and a bare "this" were marked blocking, and nobody used them (docs: document EWS03 and EIF01 health codes and guard against undocumented codes #31808). Sibling PRs got different verdicts for the same thing (feat(cli): log database migration progress on server startup #31790 blocking, feat: report database migration outcome #31849 clean).

Changes

Skill (.claude/skills/doc-check/):

• The 7 personas run in 3 groups: facts (accuracy, coverage), reader (learner, audience, structure), and language (consistency, language). A group loads each rule page once. The persona files keep all their rules.
• A change with fewer than 150 docs-relevant changed lines runs the groups inline, with no sub-agents.
• One verifier for 5 or fewer findings. More than that: two verifiers, never more.
• A style finding that does not change the meaning is a suggestion, never blocking. Blocking stays for wrong facts, missing docs for a new user-facing surface, broken markup, links, and anchors, and failing docs lint. Vale never fails, so a Vale alert is a style finding.
• A PR in a stack or backport family reads the doc-check comment its siblings got. It keeps the same verdict for the same surface, or says why it differs.
• The trace gets mode, docs_relevant_lines, groups_run, verifiers, subagents_started, and siblings. The other fields are the same, so old and new runs can be compared.

Workflow (.github/workflows/doc-check.yaml):

• Each run starts a new chat (force-new-chat) in the PR's existing review workspace (workspace-id). The prompt carries the trace from the previous chat on the PR, so a re-run does not repeat itself.
• The wait is 5 hours and the job limit is 330 minutes. A chat still running at the end of the wait now ends the job green with a notice and a link to the chat. Other chat errors still fail the job.

Why wait and not end the job when the chat starts: the job has to outlive the chat to stop the workspace when the review ends, and the per-PR concurrency group only keeps two reviews out of one workspace while the job is running. Ending the job early would lose both. The cost is a GitHub-hosted runner that polls for as long as the review takes.

Not tested on live traffic

I checked this with actionlint, zizmor, markdownlint, and a local run of the prompt step with a fake Coder API. It has not run against dogfood. To evaluate it, re-run doc-check on the same 27 PRs from the week report and compare: chats started, time to verdict, job result, and how many of the 17/3/3/4 verdicts change. Also check #31790 and #31849 together, and #31808 for style findings that block.

Overlaps: #31720 changes the same workflow to cancel the run in progress and stop the review chat. #31649 (draft) goes the other way in the skill, with more, narrower sub-agents. Only one of them should merge as is.

Generated by Coder Agents on behalf of @bpmct.