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

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 adapting 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."

> **Log:** `step.start` with `data: { skill: "erp-kit-app-2-requirements-review", context: { app: APP_NAME, flows: count, actors: count, stories: count } }`

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

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

## References

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