---
name: erp-kit-module-3-update-plan
description: Update model/command/query documentation based on plan review (step 4) feedback. Use after erp-kit-module-4-plan-review returns NEEDS CHANGES to apply targeted fixes without re-creating existing docs.
disable-model-invocation: true
metadata:
  erp-kit-version: "0.59.0"
---

# Fix Plan Documentation from Review Feedback

Apply targeted fixes to model, command, and query documentation based on plan review feedback. Unlike erp-kit-module-3-plan which creates docs from scratch, this skill reads the review report and applies only the necessary changes.

## 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 erp-kit-module-4-plan-review returns **NEEDS CHANGES**
- User wants to fix specific gaps or inconsistencies flagged by the review
- User says "fix the review findings" or "apply the review feedback"

## Step 1: Setup

Define shared context:

- `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`
- `MODEL_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/model/*.md`
- `COMMAND_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/command/*.md`
- `QUERY_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/query/*.md`

Verify that at least some model/command/query docs exist. If none exist, stop with: "No existing docs found. Use erp-kit-module-3-plan to create docs first."

## Step 2: Extract & Triage Review Findings

Look at the conversation history for the most recent plan review report (from erp-kit-module-4-plan-review). Extract all `critical` and `major` findings.

If no review report is found in conversation history, ask the user: "No review report found in this conversation. Please either run /erp-kit-module-4-plan-review first, or paste the review findings."

### Severity Re-evaluation

The review may over-classify findings. Before accepting each finding, re-evaluate it by reading the relevant feature docs:

- **"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), **reject** the finding
- **"Does the feature doc explicitly require this?"** — Only accept findings for capabilities the feature doc actually specifies. Reject findings that invent requirements the feature does not mention
- **"Does this block implementation?"** → accept as `critical`
- **"Will this cause rework during implementation?"** → accept as `major`
- Neither → downgrade to `nit` (informational only, do not fix)

### Categorize accepted findings into:

1. **Missing docs** — new model/command/query docs that need to be created
2. **Incomplete docs** — existing docs with missing fields, business rules, or error scenarios
3. **Inconsistencies** — mismatches between feature docs and model/command/query docs

## Step 3: Plan the Delta

Produce a targeted fix plan listing **only** the changes needed. Format:

### Fix Plan

**Findings rejected** (design choices or not required by feature docs):
- (list rejected findings with reason — these will NOT be fixed)

**Findings downgraded to nit** (informational, no action):
- (list downgraded findings with reason)

**Docs to create:**
- (list new docs with purpose — scaffold these)

**Docs to update:**
- (list existing docs with specific changes needed — edit in place)

**Docs unchanged:**
- (explicitly note docs that are fine — do NOT touch these)

## Step 4: Apply Fixes

For each item in the fix plan:

### Missing docs → Scaffold & Populate

Scaffold using `erp-kit` CLI. **Names must be PascalCase** (see [naming convention](references/naming.md)):

```bash
npx erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
npx erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
npx erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
```

Populate the new docs using the extraction rules from:

- [Model extraction](references/model-extraction.md)
- [Command extraction](references/command-extraction.md)
- [Query extraction](references/query-extraction.md)

### Incomplete docs → Edit in place

Read the existing doc, then edit it directly to add the missing content. Do NOT re-scaffold or overwrite.

### Inconsistencies → Align with feature spec

Read both the feature doc and the model/command/query doc, then edit the model/command/query doc to align with the feature spec.

**Important**: Do NOT touch docs listed as "unchanged."

## Step 5: Dispatch Refinement Agents (parallelize)

Launch up to 3 Agent tool calls in parallel — one per doc type that had changes — to review and refine the modified docs. Skip agents for doc types with no changes.

Each agent receives: MODULE_NAME, the list of **changed** doc file paths only, and FEATURE_DOCS for cross-reference.

| Agent | Prompt Template                                                                          | Inputs                                             |
| ----- | ---------------------------------------------------------------------------------------- | -------------------------------------------------- |
| 1     | [model-extraction.md](references/model-extraction.md)           | MODULE_NAME, changed model doc paths, FEATURE_DOCS |
| 2     | [command-extraction.md](references/command-extraction.md)       | MODULE_NAME, changed command doc paths, FEATURE_DOCS |
| 3     | [query-extraction.md](references/query-extraction.md)           | MODULE_NAME, changed query doc paths, FEATURE_DOCS |

For each agent:

1. Read the prompt template file
2. Replace `{{MODULE_NAME}}` with the resolved module name
3. Replace `{{FEATURE_DOCS}}` with the actual file paths
4. Add to the prompt: "Read the docs at [doc paths]. These were just modified to fix review findings. Cross-reference against the feature docs and the extraction rules. Fix any remaining issues. Edit files directly."
5. Dispatch the agent with the filled prompt

## Step 6: Validate

Run `pnpm run module:doc:check` and fix any violations.

## References

- [Naming convention](references/naming.md)
- [Module structure](../erp-kit-shared/references/structure.md)
- [Model extraction rules](references/model-extraction.md)
- [Command extraction rules](references/command-extraction.md)
- [Query extraction rules](references/query-extraction.md)