---
name: erp-kit-app-2-requirements-review
description: Review requirements quality and documentation consistency for applications. Use after creating Tier 1-2 documentation (requirements, actors, business-flow) with erp-kit-app-1-requirements.
metadata:
  erp-kit-version: "0.9.0"
---

# Requirements Review

Review **requirements quality** and **documentation consistency** for an application's Tier 1-2 documentation.

## Version Check

Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.

## Progress Logging

Log to the audit trail at every checkpoint. See [erp-kit-app-shared/references/progress-protocol.md](../erp-kit-app-shared/references/progress-protocol.md) for the full protocol.

```bash
npx erp-kit app progress log --json '<ProgressInput JSON>'
```

Required checkpoints: `step.start` (on invocation), `decision` (on user choices), `agent.dispatch`/`agent.result` (on subagent lifecycle), `artifact.create` (on file writes), `validation` (on `erp-kit app check` or build commands), `step.complete` (on finish), `error` (on failures).

Bundle all conversation since the last checkpoint into the `conversation` array. Use your session ID as `sessionId`. Use the user's original prompt as `prompt`.

## When to Use

- After writing application requirements and business flows (step 1)
- When validating that actors, flows, and sequences follow best practices
- When checking for gaps or inconsistencies in Tier 1-2 documentation

## Step 1: Setup

Define shared context for all agents:

- `APP_ROOT`: the app directory (e.g., `{APP_ROOT}/{APP_NAME}`). Must contain `README.md` and a `docs/` directory.
- `APP_NAME`: basename of APP_ROOT
- `APP_README`: `<APP_ROOT>/README.md`
- `BUSINESS_FLOW_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/README.md`
- `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actors/*.md`
- `STORY_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/story/*.md`

Verify at least `APP_README` exists. If not, stop with: "No application README found at <APP_ROOT>. Run erp-kit-app-1-requirements first."

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

Launch 3 Agent tool calls in parallel — one per review concern.
Each agent receives: APP_NAME, relevant doc file paths.
Each agent returns: structured markdown per [references/requirements-report-format.md](references/requirements-report-format.md).

| Agent | Prompt Template                                                                      | Inputs                                     |
| ----- | ------------------------------------------------------------------------------------ | ------------------------------------------ |
| 1     | [references/best-practices-check.md](references/best-practices-check.md)             | APP_README, ACTOR_DOCS, BUSINESS_FLOW_DOCS |
| 2     | [references/boundary-consistency-check.md](references/boundary-consistency-check.md) | APP_README, ACTOR_DOCS, BUSINESS_FLOW_DOCS |
| 3     | [references/story-quality-check.md](references/story-quality-check.md)               | APP_README, ACTOR_DOCS, BUSINESS_FLOW_DOCS, STORY_DOCS |

For each agent:

1. Read the prompt template file
2. Replace `{{APP_NAME}}` with the resolved app name
3. Replace `{{APP_README}}`, `{{ACTOR_DOCS}}`, `{{BUSINESS_FLOW_DOCS}}` with the actual file paths
4. Replace `{{STORY_DOCS}}` with the story doc file paths (agent 3 only)
5. Dispatch the agent with the filled prompt

## Step 3: Aggregate & Validate

After ALL agents return:

1. Collect the markdown results from each agent
2. Merge all `issues[]` arrays into a single list
3. Merge all `recommendations[]` arrays into a single list
4. **Filter out** any recommendation that would violate `erp-kit app check` schema constraints (e.g., title-casing business flow H1 headings)
5. Calculate totals across all summaries

## Step 4: Priority Validation

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

- **"Is this even this application's responsibility?"** — If the concern belongs to a module or is out of scope, drop it from the report
- **"Does this block proceeding to planning?"** → `critical`
- **"Will this force Tier 3-4 rework (stories, screens, resolvers)?"** → `high`
- **"Is this a quality improvement with no rework risk?"** → `medium`
- All no → `low`, regardless of subagent label

## Step 5: Render Report

## Report Format

Render the aggregated results as markdown:

### Requirements Review Report

**Application:** <APP_NAME>

---

### 1. Best Practices

| Check | Scope | Status | Detail |
| ----- | ----- | ------ | ------ |

(Populated from agent 1 issues)

---

### 2. Documentation Consistency

| Actor/Flow | Check | Status | Detail |
| ---------- | ----- | ------ | ------ |

(Populated from agent 2 issues)

---

### 3. Story Quality

| Story/Flow | Check | Status | Detail |
| ---------- | ----- | ------ | ------ |

(Populated from agent 3 issues)

---

### 4. Summary

| Aspect                    | Status | Details           |
| ------------------------- | ------ | ----------------- |
| Best Practices            |        | X/Y checks passed |
| Documentation Consistency |        | X/Y checks passed |
| Story Quality             |        | X/Y checks passed |

### 5. Recommendations

Numbered list of actionable fixes, grouped by priority:

1. Critical documentation gaps (highest priority)
2. Best practice violations
3. Improvement suggestions

## References

- [Requirements report format](references/requirements-report-format.md)
- For requirements creation, see erp-kit-app-1-requirements
