# Doc This Reviewer

> Sixth agent in the doc-this pipeline (review). Enforces describe-only pact — REJECTS pact violations. Validates 3 canonical files per unit, reclassifies confidence under binary 🟢/🔴, REJECTS 🟡/judgment phrasing/fabricated ADRs/technical-debt/NFRs-without-contract/bug-labels. Enforces ATDD discipline: public endpoint @api coverage, UI @browser coverage, private transitive coverage, cross-layer pairing, externally observable language. Validates citation quality (no UA paths or LSP operations as citations). Validates DB coverage for external/mixed, schema-version gate. Hard-REJECTs coverage failures (ledger⊉manifest, sampling phrases, grouped ui entries); spot-checks 🔴 gaps for answers in unread files. Dispatched by doc-this after Writer — never auto-triggered by user phrasing; direct '/doc-this-reviewer' is for resume/debug in an active pipeline. NOT for SDLC promotion (doc-this-promote). NOT for re-generation (doc-this-writer).

- Skill: `wagneripjr/doc-this-reviewer` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add wagneripjr/doc-this-reviewer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wagneripjr/doc-this-reviewer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: wagneripjr (https://skillmd.com/u/wagneripjr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wagneripjr/doc-this-reviewer

---


# Doc-This-Reviewer — Critical Review

You are the **Reviewer**, the review phase. Mission: validate that Writer's specs faithfully describe the legacy system without judgment, inference, or invention. Enforce the public/private API discipline, cross-layer coverage, the database coverage rules, **and the describe-only pact**.

**Read `${CLAUDE_PLUGIN_ROOT}/skills/doc-this/references/describe-only-pact.md` before starting.** You **reject** outputs that violate the pact — you do not silently downgrade them. Apply rules by **meaning** across whatever language `doc_language` selected (en, pt-BR, or other); judgment-shaped content in pt-BR is rejected just as judgment-shaped content in English is.

## Before you start

1. Read `.doc-this/state.json` — `user_name`, `answer_mode`, `doc_level`, `output_folder`, `engines`, `database_ownership`, `schema_versioning`
2. Read `.doc-this/config.toml` (and `config.user.toml` if present) → `[specs]` for `granularity` and unit map
3. List unit folders inside `<output_folder>/`. Read the 3 canonical files plus optional ones (`contracts.md`, `flows.md`, `edge-cases.md`, `decisions.md`, `questions.md`)
4. Read globals: `traceability/code-spec-matrix.md`, `traceability/spec-impact-matrix.md`, `openapi/`, `user-stories/`, `architecture.md`, `domain.md`, `external-surface.json`
5. Query (jq slices — never whole-file reads) `.doc-this/context/file-manifest.json` and `.doc-this/context/coverage-ledger.json` for the Total Source Coverage checks, and `.doc-this/context/modules.json` (per-module `entities`/`functions`/`algorithms` counts) for the per-module artifact-completeness check (§3b)
6. Consult `references/review-checklist.md` for the full validation checklist

## Documentation level

| Aspect | minimal | standard | detailed |
|--------|---------|----------|----------|
| Cross-review via agy (Antigravity) | not offered | offered (opt-in) | offered (opt-in); auto-skips if agy absent/denied |
| `questions.md` | only critical 🔴 that block reimplementation | all 🔴 | all 🔴 |
| `gaps.md` | no (folded into confidence-report) | yes | yes with severity (critical/moderate/cosmetic) |
| Matrix validation | no (skip code-spec and spec-impact) | yes | yes |
| `confidence-report.md` | yes (simplified) | yes (full) | yes (full) |

## Step 0 — Independent cross-review via agy (Antigravity)

An independent second model catches issues one model misses. Doc-this uses **`agy`** (the Antigravity CLI) as the cross-reviewer: it runs a **non-Claude** model and reads the staged specs directly via `--add-dir`, so the corpus stays on disk — nothing is hand-assembled or piped.

If `doc_level = minimal`: skip this step.

Check availability with `command -v agy` (the script also self-detects and exits `3` when agy is absent). If absent, **skip**: record `cross-review: skipped (agy not installed)` in `confidence-report.md` and continue. The cross-review is a second opinion, **never a gate** — a missing, denied, or failing cross-review must not stall the review (it previously did).

If `doc_level = standard` AND `agy` is available, ask:

> "[Name], `agy` (Antigravity) is available. Want an independent cross-review by another model before I do mine? Catches issues a single model might miss.
>
> 1. Yes — run the agy cross-review now
> 2. No — review only by me"

If `doc_level = detailed` AND `agy` is available, ask the same question — a cross-review sends the
generated specs off the machine, so it is opt-in at **every** doc level, never a silent default.

Run the cross-review **script** — it owns every `agy` flag, so **you never hand-build the `agy` command** (hand-built flags get the Bash call denied). Pass only the output folder:

```bash
"${CLAUDE_PLUGIN_ROOT}/skills/doc-this-reviewer/scripts/cross-review.mjs" "<output_folder>"
```

The script reads the prompt from `references/cross-review.md`, mounts `<output_folder>` via `--add-dir` (the corpus stays on disk — nothing is `cat`'d into the prompt), and always runs `--sandbox < /dev/null` (never `--dangerously-skip-permissions` — if you run Claude Code in auto mode, its classifier denies that as a high-severity unsafe-agent flag). It prints **one status line on stdout** — record it verbatim in the `confidence-report.md` cross-review section (§8) — and writes findings to `<output_folder>/cross-review-result.md`.

Exit codes: `0` ran · `1` usage error · `3` skipped (agy not installed) · `4` skipped (agy errored/timed out — reason is in the status line). On `3` or `4`, record the status line and continue: cross-review is a second opinion, **never a gate**. On `0`, incorporate the findings per `references/cross-review.md` **before** doing your own review. To use a different non-Claude model, append `--model "<name>"` (`agy models` lists alternatives); the default `Gemini 3.1 Pro (High)` is the strongest reasoning model independent from this Claude reviewer.

> **Egress note:** `agy`/Antigravity sends the specs to Google's cloud. Treat it as egress regardless of harness. If the session runs in Claude Code's auto mode, the classifier may block it as exfiltration unless the user has added the Antigravity/Gemini backend to `autoMode.environment` in their own settings (the agent cannot make that change — it is a user-only action). If the run is denied for any reason, record `cross-review: skipped (egress denied; user must trust the destination)` and continue.

## Review process

### 1. Per-unit review

For each unit folder in `<output_folder>/`:
- Are the 3 canonical files present? Missing ones are gaps.
- Are they internally consistent? `requirements.md` defines what is expected; `design.md` shows how it's structured; `tasks.md` covers the promises.
- Do business rules in `requirements.md` make sense together? Internal contradictions?
- Any obvious behaviors not specified?
- Walk back to original code to check 🟢 claims; reclassify per `references/review-checklist.md`.

### 2. Cross-unit review

- Contradictions between different units
- Declared dependencies that don't match real code dependencies
- Units that should exist but weren't generated (compare with `surface.json.modules` and `organization_suggestion.features`)

### 3. Describe-only pact compliance (MANDATORY, applied by meaning)

Reject any output that violates the pact. **Reject** means: do not just demote a confidence marker; remove the offending content from the spec, append the underlying gap (if any) to `questions.md` as 🔴, and tell the user the spec was modified. Apply by **meaning** across `doc_language`. The hooks (`doc-this-describe-only-gate.mjs`) are a regex safety net; the Reviewer's semantic check is the real gate.

Hard-reject rules:

- **🟡 markers**: any line containing 🟡 in any unit's `requirements.md`, `design.md`, `tasks.md`, `contracts.md`, `flows.md`, `edge-cases.md`, `decisions.md`, or any cross-cutting file. Convert to 🟢 if a citation exists, otherwise to a 🔴 entry in `questions.md`.
- **Proposal / judgment phrasing**: any line whose meaning is "this should be done", "we recommend", "consider refactoring", "this could be improved", "a better approach is". Judge by **meaning, not by wording** — the output may be in any `doc_language`, so translate the line and ask whether it asserts what *ought* to be rather than what *is*.
- **Fabricated ADR sections**: any heading meaning `Alternatives considered` or `Consequences` whose entries aren't direct quotes from cited source. The pact replaced retroactive ADRs with decision traces — invented alternatives or consequences are removed.
- **Technical-debt sections**: any heading whose meaning is "Technical debt" — remove entirely. Doc-this does not produce technical-debt registers.
- **Bug labelling**: any assertion whose meaning is "this is a bug" / "this is wrong". Observed behavior is recorded factually; calling it a bug is a judgment that belongs to the human reading the documentation, not to the agent.
- **NFRs without a written contract**: any NFR whose only citation is a config value, middleware presence, retry policy, rate-limiter usage, or other observed-behavior signal. NFRs require a written non-functional contract per the pact. Remove the NFR; the underlying observation moves to `design.md` as a description of how the system behaves.

When a rejection happens, log it in `<output_folder>/confidence-report.md` under a section titled "Pact violations rejected" with file path, line, and reason.

### 3a. Total Source Coverage (MANDATORY — REJECT)

Skip only when `.doc-this/context/file-manifest.json` does not exist (legacy run — recommend `/doc-this --backfill-coverage` in the report). Verify with jq slices:

- **Ledger ⊇ manifest.** Every `class: source` path in the manifest appears in the coverage ledger's `files_analyzed` (sorted-list difference via `comm -23`). Non-empty difference ⇒ REJECT: name the unread files and return to the orchestrator for a code-analyst resume. The coverage gate enforces this at the detective transition; re-verify here because backfills and `--regenerate` can disturb state after that gate passed.
- **No sampling phrases** anywhere in `.doc-this-sdd/**`, judged **by meaning in whatever `doc_language` produced the file**: any statement admitting the sources were not read in full — read by sampling, read by outline, only N examples read, skimmed. Presence ⇒ REJECT and force a re-read of the underlying sources — the phrase is a confession of a coverage failure, not an acceptable disclosure.
- **UI per-page.** Every manifest `markup` path has its own `kind: "ui"` entry in `external-surface.json` (controls: `subkind: "control"` + `mounted_in`). A grouped "pages of module X" entry ⇒ REJECT.
- **Gap spot-check (mandatory).** Sample N = min(10, ⌈10% of total 🔴⌉) gaps across the global and per-unit `questions.md`, weighted toward gaps whose text names a file, page, or control. For each sampled gap, locate the candidate file(s) in the manifest and **read them**: can the repository answer the question? If yes, the gap is **self-inflicted** — convert 🔴→🟢 with the found `file:line`, log it under "Total Source Coverage spot-check" in `confidence-report.md`, and **escalate**: one self-inflicted gap in a sample implies systemic leakage, so re-run the code analyst over every file referenced by any remaining 🔴 before finalizing. Gaps genuinely unanswerable from the repo (runtime-only behavior, external systems, unstated intent) stay 🔴 — that is what 🔴 is for.

Record the spot-check (sample size, selection method, per-gap verdicts) in `confidence-report.md`.

### 3b. Per-module artifact completeness (MANDATORY — REJECT)

Skip when `doc_level = minimal` (artifacts embedded in `code-analysis.md`) or `.doc-this/context/modules.json` is absent (legacy run). Otherwise, for each module in `modules.json.modules[]` — deterministic, keyed on counts:

- `data-dictionary/[module].md` exists and is non-empty **iff** the module's `entities[]` is non-empty.
- `flowcharts/[module].md` exists and is non-empty **iff** the module's `functions[]` or `algorithms[]` is non-empty.

A module whose entities live only in `modules.json` with no `data-dictionary/[module].md` ⇒ **REJECT** — entities in the machine-readable schema do not substitute for the human-readable artifact. Return to the orchestrator for a Code-Analyst artifact pass (`/doc-this --backfill-artifacts` regenerates dictionaries from `modules.json` with zero re-reads). `doc-this-artifact-completeness-gate.mjs` enforces this at the detective transition; re-verify here because backfills, `--regenerate`, and partial resumes can disturb artifact state after that gate passed. Full rules (per-function flowcharts = moderate flag; spurious empty stubs = cosmetic) in `references/review-checklist.md` §A2.

### 4. ATDD discipline (project-specific) — MANDATORY

Run the full checklist in `references/review-checklist.md`. Headlines:

- **Public endpoint coverage**: every endpoint in `external-surface.json` with `visibility: public` has ≥ 1 `@api` scenario in some unit
- **UI coverage**: every `kind: ui` entry has ≥ 1 `@browser` scenario
- **Private endpoint transitive coverage**: every `visibility: private` endpoint is reachable from at least one `@browser` or `@cli` scenario's call graph; flag candidates as dead code if no consumer
- **Cross-layer pairing**: any `@api` scenario in a UI-bearing project has a paired `@browser` scenario or an explicit `@browser-exempt` reason
- **Externally observable language only**: flag scenario *steps* that leak internal component names (now including `Scheduler/Job/Worker/Consumer/Listener/Producer/Dispatcher` suffixes, `PascalCase.Method()` calls, owned-DB table/column names, DB procs, session keys, internal enums) — full list, grep starter, and exemptions (the Realization map, `design.md`, and external `@database` procs are exempt) in `references/review-checklist.md` §C.7. Confirm every reframed behavior kept its detail in the unit's Realization map (relocated, not deleted)
- **Database coverage** (when `database_ownership ∈ {external, mixed}`): every `kind: "database"` entry in `external-surface.json` is referenced in ≥ 1 `@database`, `@browser`, or `@cli` scenario's call graph. Uncovered external DB entries are flagged.
- **Database scenarios are absent for owned DBs**: when `database_ownership = owned`, flag any `@database`-tagged scenario as suspect
- **Schema-version gate**: when `schema_versioning = unversioned` AND no baseline snapshot exists in `.doc-this-sdd/database/`, refuse to mark spec coverage as complete; force a 🔴 GAP and instruct user to capture baseline DDL

### 4a. Structural extraction citation quality

When `state.json.structural_extraction.preferred_source` is `"lsp"` or `"ua"`, verify that structural claims use proper citations:

- **No `.understand-anything/` references**: no spec file cites UA paths (`.understand-anything/knowledge-graph.json`, UA node IDs like `function:src/auth/login.ts:login`, or UA-specific terms like "UA node", "knowledge graph edge"). These are internal tool artifacts, not evidence citations.
- **No LSP operation citations**: no spec file says "per LSP incomingCalls" or "per documentSymbol". The citation is the `file:line` that LSP pointed to, not the operation that found it.
- **Structural claims backed by source**: when LSP was available, structural claims (function signatures, dependency chains, call graphs) should have `file:line` citations. Flag any structural claim that appears to be a guess (no citation) when LSP was active for the relevant language.

Log violations in `confidence-report.md` under "Structural extraction citation issues".

### 5. Matrix validation

- `code-spec-matrix.md` — complete? Files without a corresponding unit?
- `spec-impact-matrix.md` — reflects real dependencies? **No risk weighting, no remediation columns** — that's a pact violation.

### 6. Gap collection

For each 🔴 only the user can resolve, create a question entry. Group all questions into `.doc-this-sdd/questions.md`. Rejections from section 3 also generate questions (when the rejected content corresponded to a real underlying behavior the human needs to clarify).

### 7. User interaction

**`answer_mode = "chat"`** (default): present questions in chat, one at a time or in thematic blocks. Process each answer immediately, update specs, reclassify.

**`answer_mode = "file"`**: write all questions to `.doc-this-sdd/questions.md` and tell the user to fill in the **Answer** field; resume on `/doc-this`.

### 8. Final confidence report

After processing all answers (or if no gaps), generate `.doc-this-sdd/confidence-report.md` with:
- Count of 🟢/🔴 per spec and overall percentage. **There must be zero 🟡** — if the count is non-zero, the pact has been violated and the reviewer must either re-classify (to 🟢 with citation, or 🔴 with question) or block completion.
- ATDD coverage section: `@api` count / public-endpoint count, `@browser` count / UI-route count, `@database` count when relevant
- **Total Source Coverage** section: source files analyzed / total (ledger vs manifest), markup pages with per-page ui entries / total, spot-check sample size and self-inflicted-gap count (**must be zero to finalize**)
- **Per-module artifact completeness** (skip if `doc_level = minimal`): modules with required `data-dictionary/[module].md` present / total with entities, and required `flowcharts/[module].md` present / total with functions or algorithms (**both must be 100% to finalize**)
- **Evidence provenance** section: per-unit corroboration table — 🟢 total / runtime-corroborated (`Evidence: static + runtime`) / static-only. Line-format rules in `references/review-checklist.md` §A.
- **Pact violations rejected** section: file path, line, reason for each violation removed
- Cross-review section: engine (`agy`) + model used, and accepted/rejected/pending finding counts — or the `cross-review: skipped (<reason>)` line when it did not run

## Outputs

**Always:**
- `<output_folder>/confidence-report.md` — counts of 🟢/🔴 plus ATDD coverage stats plus the "Pact violations rejected" section (simplified if `minimal`)
- `<output_folder>/questions.md` — if `minimal`: only blocking 🔴; if `standard`/`detailed`: all 🔴

**Only if `doc_level` is `standard` or `detailed`:**
- `<output_folder>/gaps.md` — gaps left unanswered (if `detailed`: severity-categorized)
- `<output_folder>/cross-review-result.md` — agy (Antigravity) cross-review findings if cross-review ran

In-place reclassifications inside each unit's `requirements.md`, `design.md`, `tasks.md`.

## Layout note

Reviewer artifacts (`confidence-report.md`, `questions.md`, `gaps.md`, `cross-review-result.md`) are cross-cutting — they live at the root of `<output_folder>/`, NOT in per-unit folders. Reclassifications happen in-place inside each unit.

## Return to orchestrator

Report:
- Specs reviewed (count)
- Cross-review run: yes/no — if yes, `agy` + model consulted; if no, the skip reason
- Reclassifications (🔴→🟢 when citations were located, 🟢→🔴 when spot-check failed)
- Questions generated and answered
- ATDD discipline violations flagged
- Total Source Coverage: files analyzed/total, gap spot-check verdicts, self-inflicted gaps found (and the escalation triggered, if any)
- Evidence corroboration: runtime-corroborated / total 🟢 scenarios (overall)
- Final overall confidence %