---
name: erp-kit-module-4-plan-review
description: Review parity between feature documentation and command/model/query documentation. Use after creating implementation plan (step 3) to validate completeness.
disable-model-invocation: true
metadata:
  erp-kit-version: "0.59.0"
---

# Feature Parity Review

Review **documentation consistency** between feature specs and command/model/query docs.

## 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 writing feature documentation, check for gaps in command/model/query documentation
- After writing command/model/query documentation, verify consistency with features
- Quality check during documentation 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
- `FEATURE_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/feature/*.md`
- `COMMAND_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/command/*.md`
- `QUERY_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/query/*.md`
- `MODEL_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/model/*.md`

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

## Step 2: Dispatch Agents (parallelize if possible)

Launch 4 Agent tool calls in parallel — one per parity check.
Each agent receives: MODULE_NAME, relevant doc file paths.
Each agent returns: structured JSON per [references/parity-report-format.md](references/parity-report-format.md).
If a doc directory is empty, the agent reports "no docs found" and skips.
Otherwise, query each sequentially.

| Agent | Prompt Template                                                                    | Inputs                     |
| ----- | ---------------------------------------------------------------------------------- | -------------------------- |
| 1     | [references/feature-command-parity.md](references/feature-command-parity.md)       | FEATURE_DOCS, COMMAND_DOCS |
| 2     | [references/feature-query-parity.md](references/feature-query-parity.md)           | FEATURE_DOCS, QUERY_DOCS   |
| 3     | [references/feature-model-parity.md](references/feature-model-parity.md)           | FEATURE_DOCS, MODEL_DOCS   |
| 4     | [references/command-model-consistency.md](references/command-model-consistency.md) | COMMAND_DOCS, MODEL_DOCS   |

For each agent:

1. Read the prompt template file
2. Replace `{{MODULE_NAME}}` with the resolved module name
3. Replace `{{FEATURE_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_DOCS}}` with the actual file paths
4. Dispatch the agent with the filled prompt

## Step 3: Aggregate Results

After ALL agents return:

1. Collect the JSON results from each agent
2. Merge all `gaps[]` arrays into a single list
3. Merge all `inconsistencies[]` arrays into a single list
4. Deduplicate: if two gaps share the same `source + target + check`, keep only one
5. 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 a real gap or a design choice?"** — If the feature intentionally omits a command/query/model (e.g., handled by another module, deferred to a later phase, or covered by a generic mechanism), drop it from the report
- **"Does the feature doc explicitly require this?"** — Only flag gaps for capabilities the feature doc actually specifies. Do not invent requirements the feature does not mention
- **"Does this block implementation?"** → `critical`
- **"Will this cause rework during implementation?"** → `major`
- All no → `nit`, regardless of subagent label

## 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):

### Feature Parity Review Report

**Module:** <MODULE_NAME>

---

### 1. Summary

| Aspect                      | Status | Details           |
| --------------------------- | ------ | ----------------- |
| Feature → Command Coverage  |        | X/Y checks passed |
| Feature → Query Coverage    |        | X/Y checks passed |
| Feature → Model Coverage    |        | X/Y checks passed |
| Command → Model Consistency |        | X/Y checks passed |

### 2. Recommendations

Numbered list of actionable fixes, grouped by severity:

1. `critical` — missing required docs, fundamental parity gaps (must fix)
2. `major` — missing business rules, incomplete error scenarios (should fix)
3. `nit` — minor naming inconsistencies, optional improvements (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

- [Parity report format](references/parity-report-format.md)
- For implementation patterns (models, commands, testing), see erp-kit-module-5-impl