---
name: erp-kit-module-6-impl-review
description: Review implementation parity between documentation and code. Use after TDD implementation (step 5) to validate code matches documentation.
disable-model-invocation: true
metadata:
  erp-kit-version: "0.59.0"
---

# Implementation Parity Review

Review **implementation consistency** between documentation and actual code.

## Version Check

Run `npx erp-kit internal measure versions` from the repo root. If `status` is `"violations"`, relay the findings (each states its own fix) and stop; otherwise proceed.

## When to Use

- After TDD implementation (step 5), verify it matches documentation
- Before merging feature branches
- Quality check during code review

## Step 1: Setup

Define shared context for all agents:

- `MODULES_ROOT`: glob `**/modules/*/README.md` and derive the parent directory
- `MODULE_NAME`: from argument or detect from current working directory
- `MODEL_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/model/*.md`
- `COMMAND_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/command/*.md`
- `MODEL_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/db/*.ts`
- `COMMAND_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/command/*.ts` (exclude `*.test.ts` and `*.generated.ts`)
- `COMMAND_TEST_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/command/*.test.ts`
- `QUERY_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/query/*.md`
- `QUERY_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/query/*.ts` (exclude `*.test.ts` and `*.generated.ts`)
- `QUERY_TEST_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/query/*.test.ts`
- `ERROR_DEFS`: `<MODULES_ROOT>/<MODULE_NAME>/lib/errors.generated.ts`

Verify at least `MODEL_DOCS`, `COMMAND_DOCS`, or `QUERY_DOCS` is non-empty. If no docs exist, stop with: "No docs found for module <MODULE_NAME>."

## Step 2: Dispatch Agents (parallelize ALL agents in a single message)

Split checks into agents by **domain + file batch**, not by check type. Command checks (C-1, C-2, C-3) run together in one agent per batch; query checks (Q-1, Q-2, Q-3) run together in one agent per batch. Launch **ALL agents in a single message** — do NOT wait for one domain to finish before starting another.

If a doc or code directory is empty, skip that domain entirely.

### Splitting Strategy

1. **Domain grouping**: C-1 + C-2 + C-3 in the same agent. Q-1 + Q-2 + Q-3 in the same agent. M-1 is its own agent.
2. **File batching**: If a domain has more than 5 doc files, split docs into batches of 3-5 files each. Each batch becomes its own agent.
3. **Corresponding code/test files**: When batching by doc files, include only the matching code and test files for those specific docs (match by filename stem, e.g., `docs/command/createFoo.md` → `command/createFoo.ts` + `command/createFoo.test.ts`).

### Agent Table

| Agent Type    | Domain  | Prompt Templates (all included in one agent)                                                                                                                                                                                                                                                     | Inputs per agent                                                                    |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| M-1           | Model   | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)                                                                                                                                                                                                                       | MODEL_DOCS (batch), MODEL_CODE (matching)                                           |
| C-1 + C-2 + C-3 | Command | [references/command-doc-code-parity.md](references/command-doc-code-parity.md) + [references/command-error-implementation-parity.md](references/command-error-implementation-parity.md) + [references/command-doc-test-parity.md](references/command-doc-test-parity.md) | COMMAND_DOCS (batch), COMMAND_CODE (matching), COMMAND_TEST_CODE (matching), ERROR_DEFS |
| Q-1 + Q-2 + Q-3 | Query   | [references/query-doc-code-parity.md](references/query-doc-code-parity.md) + [references/query-error-implementation-parity.md](references/query-error-implementation-parity.md) + [references/query-doc-test-parity.md](references/query-doc-test-parity.md)    | QUERY_DOCS (batch), QUERY_CODE (matching), QUERY_TEST_CODE (matching), ERROR_DEFS   |

### Batching Example

If a module has 8 command docs: split into 3 batches (3+3+2). Each batch spawns 1 agent (C-1+C-2+C-3) → 3 command agents total. If it has 4 command docs: no batching needed, 1 agent.

For model docs: if 6 models → 2 batches (3+3) → 2 agents (M-1 × 2). If 3 models → 1 agent.

### Agent Dispatch

For combined agents (command or query), concatenate all prompt templates in order, then fill placeholders. For each agent:

1. Read [claim-verification.md](../erp-kit-shared/references/claim-verification.md) and all prompt template files for that agent type
2. Concatenate them in order — claim-verification.md first — with a `---` separator between each
3. Replace `{{MODULE_NAME}}` with the resolved module name
4. Replace template placeholders (`{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{QUERY_CODE}}`, `{{COMMAND_TEST_CODE}}`, `{{QUERY_TEST_CODE}}`, `{{ERROR_DEFS}}`) with the actual file paths **for this batch only**
5. Dispatch the agent with the filled prompt; instruct it to return a **single JSON result** with combined `gaps[]` and `inconsistencies[]` covering all check types

**IMPORTANT**: Launch ALL agents across ALL domains in a single parallel message. Do not serialize by domain.

## Step 3: Aggregate Results

After ALL agents return:

1. Collect the JSON results from each agent
2. **Validate claim accounting**: if a result has no `claims_total`, or `total_checks < claims_total`, or contains a `pass` without `evidence`, re-run that agent once; on second failure treat its unevidenced passes as `fail`
3. **Merge batches**: If a check type was split across multiple batches (e.g., C-1 batch 1 + C-1 batch 2), merge their `gaps[]` and `inconsistencies[]` into a single result per check type
4. Merge all `gaps[]` arrays across all check types into a single list
5. Merge all `inconsistencies[]` arrays into a single list
6. Deduplicate: if two gaps share the same `source + target + check`, keep only one
7. Calculate totals across all summaries

## Step 4: Severity Validation

Subagents tend to over-classify. Before rendering the report, re-evaluate every non-pass finding:

- **"Is this actually documented as a requirement?"** — If the doc does not explicitly specify the field, state, or behavior, drop it from the report. Do not invent requirements the documentation does not mention
- **"Is this a framework convention, not a doc gap?"** — If the finding is about generated shells, boilerplate, or patterns that the framework handles automatically, drop it
- **"Does this break the doc-code contract?"** → `critical` (missing implementation of documented feature, missing model fields/states)
- **"Will this cause rework or missed behavior?"** → `major` (incomplete business rule implementation, missing test for documented scenario)
- All no → `nit`, regardless of subagent label (minor naming difference, optional JSDoc, cosmetic issue)

## Step 5: Determine Verdict

- **APPROVED**: zero `critical` and zero `major` findings (nits only, or all pass)
- **NEEDS CHANGES**: one or more `critical` or `major` findings

## Step 6: Render Report

Render the aggregated results as markdown (after severity validation):

### Implementation Parity Review Report

**Module:** <MODULE_NAME>

---

### 1. Summary

| Aspect                              | Status | Details           |
| ----------------------------------- | ------ | ----------------- |
| Model Doc → Code Coverage           |        | X/Y checks passed |
| Command Doc → Code Coverage         |        | X/Y checks passed |
| Command Error Implementation        |        | X/Y checks passed |
| Command Test Coverage               |        | X/Y checks passed |
| Query Doc → Code Coverage           |        | X/Y checks passed |
| Query Error Implementation          |        | X/Y checks passed |
| Query Test Coverage                 |        | X/Y checks passed |

### 2. Recommendations

Numbered list of actionable fixes, grouped by severity:

1. `critical` — missing model fields/states, broken doc-code contract (must fix)
2. `major` — missing business rules, incomplete test coverage (should fix)
3. `nit` — minor naming differences, optional JSDoc, cosmetic issues (informational only)

### 3. Verdict

**Verdict: APPROVED / NEEDS CHANGES**

- If APPROVED with nits: "Review passed. The following nits are informational and do not block progress:" followed by the nit list.
- If NEEDS CHANGES: "Review requires changes. Fix all critical and major issues, then re-run the review."

Severity counts: `critical: N, major: N, nit: N`

## References

- [Implementation parity report format](references/impl-parity-report-format.md)
- [Command patterns](references/commands.md)
- [Error patterns](references/errors.md)
- [Testing patterns](../erp-kit-shared/references/testing.md)