#432 Add deep-review-docs agent + wire into /deep-review-next orchestrator

[hubertgajewski]

Summary

Adds .claude/agents/deep-review-docs.md — a documentation-consistency specialist agent for the /deep-review-next orchestrator under epic #436. The agent verifies that staged + unstaged changes are reflected in the right doc per the project's documented split rules (README.md = reference, CLAUDE.md = behavioral, .claude/skills/<n>/SKILL.md = workflow ownership). It runs read-only (Read, Grep, Glob), receives the diff inline from the orchestrator like the other sibling agents, and emits findings in the shared pass / fail / N/A schema (matches deep-review-project-checklist.md).

Per the sibling pattern (PRs #426 / #427 / #428 / #429 / #444), this PR also wires deep-review-docs into /deep-review-next: adds the row to the current roster table, removes the row from the Pending table, adds an unconditional Task(...) dispatch in Step 1's parallel batch (the agent has a No-op case checklist item that returns empty findings on doc-irrelevant diffs — matches AC4), adds the ### deep-review-docs section to the Step 2 aggregate output, and extends the total: line and status: rule to include <DF> docs fail / zero docs fail.

Closes #432
Contributes to #436

DoD coverage

#	DoD item	Where
1	.claude/agents/deep-review-docs.md written with split rules encoded as a checklist	.claude/agents/deep-review-docs.md lines 23–43
2	Verifies the four split rules (new files in README structure block, new workflows in README CI table, behavioral rules in CLAUDE.md, workflow steps in the relevant SKILL.md)	Checklist items 1, 2, 5, 6
3	Frontmatter declares tools and model	Lines 1–6: tools: Read, Grep, Glob, model: sonnet
4	Estimate = 2 set in Project #1	Pending — set on the issue pre-merge (Project #1 Estimate/Actual hours live on issues, not PRs)
5	Actual hours recorded in Project #1	Pending — set on the issue post-merge

Acceptance criteria mapping

AC	Where satisfied
Diff adds new file/directory → verifies README.md Repository structure block	Checklist item 1 ("New file or directory")
Diff modifies CI workflow → verifies CI workflows description in README.md	Checklist item 2 ("New or modified CI workflow")
Diff changes Claude-facing behavior → verifies it goes in CLAUDE.md vs. a skill file	Checklist items 5 ("Behavioral rule for Claude") + 6 ("Workflow step")
Diff with no doc-relevant changes → empty findings	Checklist item 9 ("No-op case")

Scope notes

• The agent extends beyond the minimum DoD by also covering: new CI repository variables (.vars.example + README CI variables table), new .env keys (.env.example + README Credentials), coverage-matrix drift, and .mcp.json server-list changes. These are implied by the same split philosophy in CLAUDE.md and parallel sibling project-checklist coverage; they are not additional acceptance criteria.
• Inputs paragraph reuses sibling wording. The "You receive the diff inline from the orchestrator" paragraph is the same idiom used in deep-review-simplification.md. Claude Code agent files have no include mechanism, so the wording is intentionally repeated rather than diverged. If/when more sibling agents are added, this is a known maintenance hazard worth tracking but not worth solving with a one-off divergence here.
• Unconditional dispatch was the design choice. Unlike deep-review-typescript / deep-review-python (gated by file extension), deep-review-docs runs on every diff. Rationale: AC4 explicitly delegates the no-op case to the agent itself, and the agent's primary check ("any added file or directory must appear in README structure block") is true on most non-trivial diffs — a glob-gate would skip very few runs.

Test plan

• git diff origin/main --stat shows two files: .claude/agents/deep-review-docs.md (new, 56 lines), .claude/skills/deep-review-next/SKILL.md (+11/-3, orchestrator wiring).
• Frontmatter name, description, tools: Read, Grep, Glob, model: sonnet set per issue spec.
• Checklist encodes all four DoD As a tester I want to have code formatter #2 split rules + the No-op case for AC4.
• Orchestrator wiring: agent appears in current roster table at .claude/skills/deep-review-next/SKILL.md:26; row removed from Pending table; unconditional Task(...) call appears in the Step 1 parallel batch at :111; ### deep-review-docs section + <DF> docs fail counter + zero docs fail status condition added at :167/:172/:173.
• All paths the agent references exist on main: .env.example, .vars.example, .mcp.json, playwright/typescript/coverage-matrix.json.
• Output schema (<pass> pass / <fail> fail / <N/A> N/A + Failures: none. closing line) matches sibling deep-review-project-checklist.md.
• Closing line cites /deep-review-next (not the legacy /deep-review) — aligned with #425 Rename /deep-review to /deep-review-next in REFERENCES + project-checklist agent prose #451.
• /security-review (manual against this branch's diff): clean — no executable code, no secrets, no auth surface, Markdown only.
• /deep-review checklist: 2 pass / 0 fail / 12 N/A (Markdown-only diff exercises the consistency item; rest are playwright/typescript/-specific).
• CI lint workflow (playwright-typescript-lint.yml) is N/A for this PR (no playwright/typescript/** changes); GitHub will skip it.
• /deep-review-next end-to-end smoke that exercises the new dispatch (verifies deep-review-docs returns the expected schema and the aggregate counters wire up correctly). Sequence with the other agent rollouts; not tracked here.

[claude]

Review — PR #452

Files reviewed: .claude/agents/deep-review-docs.md (59-line new agent), .claude/skills/deep-review-next/SKILL.md (+11/-3 orchestrator wiring)

deep-review-docs.md — agent definition

• Frontmatter ✅ name: deep-review-docs, description, tools: Read, Grep, Glob, model: sonnet all set correctly per issue #432 spec.
• Checklist (lines 35–51): all 6 split rules encoded — new file/directory (README structure block), CI workflow drift, CI repository variables, .env keys, behavioral rules in CLAUDE.md, workflow steps in SKILL.md — plus coverage-matrix and MCP server items (scope extension per PR body). No-op case (line 51) handles AC4.
• Output format (lines 53–65): pass/fail/N/A + Summary: X pass / Y fail / Z N/A + ordered failure list with file:line — matches sibling deep-review-project-checklist.md schema. Closes with Failures: none. per spec.
• Inputs paragraph (lines 22–24): identical wording to deep-review-simplification.md — maintained as a known cross-agent hazard per the PR body's scope notes. Not a blocking issue.

deep-review-next/SKILL.md wiring

• Roster table (line 74): deep-review-docs row added with correct description; trailing | and column alignment match existing rows.
• Roadmap table (line 82): deep-review-docs | #432 row removed — consistent with the same move in sibling PRs.
• Task dispatch (lines 91–93): unconditional Task(subagent_type="deep-review-docs", ...) placed in the parallel batch before conditional dispatches, as specified in the orchestrator.
• Aggregate output (lines 101–103): ### deep-review-docs section + Summary: <pass> / <fail> / <N/A> added at the right position (after python, before aggregate block).
• Aggregate total + status (lines 108–109): / <DF> docs fail appended to total:; and zero docs fail added to the status: ready-condition. Both extend the existing schema without altering the existing segments.

No-op checklist item

The new agent's item 9 ("No-op case") correctly delegates the AC4 requirement (empty findings on doc-irrelevant diffs) to the agent. Since the diff is doc-shaped, this item is not applicable for this review.

Verdict

All checklist items pass. Orchestrator wiring is mechanically correct and consistent with the sibling-pattern PRs (#426/#427/#428/#429/#444). No Playwright, TypeScript, or Python files are in scope — project-checklist and language-specialist agents would be SKIPPED.

Approve.

Reviewed by proxy/@preset/minimax-minimax-m2-7-no-thinking

[claude]

Summary

PR #432 adds the deep-review-docs specialist agent and wires it into the /deep-review-next orchestrator. Two files changed: a new agent definition file and an updated orchestrator SKILL.md.

What was reviewed: agent file correctness, SKILL.md consistency, README/CLAUDE.md split compliance.

deep-review-docs.md (new file)

• Agent name/type deep-review-docs matches the subagent_type referenced in the Task call — ✅
• Model sonnet is a valid override value — ✅
• tools block (Read, Grep, Glob) is appropriate for a docs-only reviewer — ✅
• Agent is correctly placed in .claude/agents/ — consistent with the project's documented agent directory

deep-review-next/SKILL.md (modified)

• New row added to the agent roster table with a concise description — ✅
• Roadmap entry deep-review-docs | #432 removed (story is being shipped) — ✅
• Unconditional Task(...) dispatch added in the correct location (between architecture and ci dispatches) — ✅
• Aggregate block updated to track <DF> docs fail count — ✅
• status formula updated to block on docs fail — ✅

Documentation split compliance

• The agent definition (new file under .claude/agents/) is correctly placed per the README's repository structure — existing entry already covers this directory
• SKILL.md remains the single source of truth for the orchestrator workflow — ✅
• CLAUDE.md MCP servers table and README MCP servers section are unchanged (no new server) — N/A
• No new CI workflow, env var, or .env key added — N/A
• Behavioral rule not introduced — N/A

Consistency with existing patterns

• New agent follows the same frontmatter + role-prompt structure as every existing agent file — ✅
• Task(...) dispatch pattern matches the unconditional dispatches above it — ✅
• Roadmap removal on issue completion is consistent with the project's documented lifecycle

No blocking issues. The PR correctly implements the planned deep-review-docs agent, removes its roadmap entry, and integrates it into the orchestrator with proper accounting in the aggregate block.

Reviewed by proxy/@preset/minimax-minimax-m2-7-no-thinking