---
name: erp-kit-app-4-plan-review
description: Review parity between Tier 2 (business flows, actors, stories) and Tier 3-4 (screens, resolvers). Use after creating plan documentation with erp-kit-app-3-plan to validate completeness.
disable-model-invocation: true
metadata:
  erp-kit-version: "0.59.0"
---

# Documentation Parity Review

Review **documentation consistency** across Tier 2 (business flows, actors, stories), Tier 3 (screens), and Tier 4 (resolvers) documentation.

## 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.

## Progress Logging

Run `npx erp-kit app progress schema` once to load the schema before your first log. Log at every step boundary marked with **Log:** below using `npx erp-kit app progress log --json '<payload>'`. Every payload requires: `v` (always `1`), `sessionId`, `prompt` (user's original request), `event`, `data`, and `conversation` (array of `{role, message}` since last log). See [progress-protocol.md](../erp-kit-shared/references/progress-protocol.md) for the full schema reference.

## When to Use

- After writing Tier 3-4 documentation, check for gaps
- Before proceeding to implementation (step 5)
- Quality check during documentation review

## Step 1: Setup

Define shared context for all agents:

- `APP_ROOT`: from argument or current working directory. Must contain a `docs/` directory.
- `APP_NAME`: basename of APP_ROOT
- `BUSINESS_FLOW_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/README.md`
- `STORY_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/story/*.md`
- `SCREEN_DOCS`: glob `<APP_ROOT>/docs/screen/*.md`
- `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actor/*.md`
- `RESOLVER_DOCS`: glob `<APP_ROOT>/docs/resolver/*.md`
- `MODULE_METADATA`: run `pnpm erp-kit doc modules --format json` and capture the JSON output. This provides authoritative module names, commands, queries, models, and dependencies for validation.

Verify at least `BUSINESS_FLOW_DOCS` is non-empty. If no business flow docs exist, stop with: "No business flow docs found under <APP_ROOT>/docs/."

> **Log:** `step.start` with `data: { skill: "erp-kit-app-4-plan-review", context: { app: APP_NAME, flows: count, stories: count, screens: count, resolvers: count } }`

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

Dispatch agents in parallel — one per item in each group. All groups are dispatched simultaneously.

Each agent receives: APP_NAME and the relevant doc file paths for its item.
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.

| Group | Prompt Template                                                                      | Per-item scope             | Inputs per agent                              |
| ----- | ------------------------------------------------------------------------------------ | -------------------------- | --------------------------------------------- |
| A     | [references/business-flow-story-parity.md](references/business-flow-story-parity.md) | One per business flow      | Single BUSINESS_FLOW_DOC + its STORY_DOCS     |
| B     | [references/actor-flow-parity.md](references/actor-flow-parity.md)                   | One per actor              | Single ACTOR_DOC + all BUSINESS_FLOW_DOCS     |
| C     | [references/story-screen-parity.md](references/story-screen-parity.md)               | One per story              | Single STORY_DOC + all SCREEN_DOCS            |
| D     | [references/story-resolver-parity.md](references/story-resolver-parity.md)           | One per story              | Single STORY_DOC + all RESOLVER_DOCS + MODULE_METADATA |
| E     | [references/orphan-detection.md](references/orphan-detection.md)                     | One global agent           | ALL doc paths + MODULE_METADATA               |

For each agent:

1. Read the prompt template file
2. Replace `{{APP_NAME}}` with the resolved app name
3. Replace doc path placeholders with the actual file paths for that item
4. Replace `{{MODULE_METADATA}}` with the JSON output (Group D and E agents only)
5. Dispatch the agent with the filled prompt

With F flows, A actors, and S stories, this produces F + A + S + S + 1 parallel agents.

> **Log:** `agent.dispatch` for each group with `data: { agentName: "group-A|B|C|D|E", task: "<description>", inputs: { flow/actor/story: "<name>" } }`

## 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 agents report the same gap (same `source + target + check`), keep only one
5. Calculate totals across all summaries
6. Render the final report below

## Report Format

Render the aggregated results as markdown:

### Documentation Parity Review Report

**Application:** <APP_NAME>

---

### 1. Business Flow → Story Coverage

| Business Flow | Flow Steps | Required Stories | Documented Stories | Gap |
| ------------- | ---------- | ---------------- | ------------------ | --- |

(Populated from agent 1 gaps where check is `story_existence`)

---

### 2. Actor Coverage in Stories

| Business Flow | Actor | Referenced in Stories | Status |
| ------------- | ----- | --------------------- | ------ |

(Populated from agent 1 gaps where check is `actor_coverage`)

---

### 3. Actor → Business Flow Coverage

| Actor | Authorized Flows | Documented Flows | Gap |
| ----- | ---------------- | ---------------- | --- |

(Populated from agent 2 gaps where check is `flow_existence`)

---

### 4. Story → Screen Coverage

| Story | Referenced Screens | Documented Screens | Gap |
| ----- | ------------------ | ------------------ | --- |

(Populated from agent 3 gaps where check is `screen_existence`)

---

### 5. Story → Resolver Coverage

| Story | Resolver Status | Required Resolvers | Documented Resolvers | Gap |
| ----- | --------------- | ------------------ | -------------------- | --- |

(Populated from agent 4 gaps where check is `resolver_existence`)

---

### 6. Orphan Detection

| Type | File | Issue |
| ---- | ---- | ----- |

(Populated from agent 5 gaps)

---

### 7. Link Validity

| Source | Target | Status |
| ------ | ------ | ------ |

(Populated from all agents' gaps where check is `link_validity`)

---

### 8. Inconsistencies

| Type | Location | Issue |
| ---- | -------- | ----- |

(Populated from all agents' `inconsistencies[]`)

---

### 9. Summary

| Aspect                | Status | Details           |
| --------------------- | ------ | ----------------- |
| Business Flow → Story |        | X/Y checks passed |
| Actor → Flow          |        | X/Y checks passed |
| Story → Screen        |        | X/Y checks passed |
| Story → Resolver      |        | X/Y checks passed |
| Orphan Detection      |        | X/Y checks passed |

### 10. Recommendations

Numbered list of actionable fixes, grouped by priority:

1. Create missing docs (highest priority)
2. Fix broken links
3. Remove or link orphans

> **Log:** `step.complete` with `data: { status: "pass"|"fail"|"blocked", summary: "<one-line verdict with gap/inconsistency counts>", artifacts: [] }`

## References

- [Link format reference](../erp-kit-shared/references/link-format-reference.md)
- [Parity report format](references/parity-report-format.md)
- For plan creation, see erp-kit-app-3-plan
- For implementation, see erp-kit-app-5-impl-backend