---
name: erp-kit-app-1-requirements
description: Create Tier 1-2 documentation (requirements, actors, business-flow) for an application. Use when starting a new application or documenting high-level requirements and workflows.
metadata:
  erp-kit-version: "0.9.0"
---

# Application Requirement Analysis Workflow

Create Tier 1-2 documentation: Requirements, Actors, and Business Flows.

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

## Workflow Phases

```
GATHER → CLARIFY → CREATE → STORY EXTRACTION → VALIDATE
```

### Phase 1: Gather

Understand the application's purpose and scope:

1. **Identify** what the application does (business purpose)
2. **List** target users (actors) and their roles
3. **Understand** business goals and success criteria
4. **Capture** key workflows the application must support

Focus on "what" the application should do, not "how" it will be implemented.

### Phase 2: Clarify

Use AskUserQuestion to clarify undefined requirements. Focus on business-level scope and workflows — not platform capabilities like authentication.

| Category         | Example Questions                                                           |
| ---------------- | --------------------------------------------------------------------------- |
| Scope            | Which steps are MVP-essential? Any steps that can be deferred?              |
| Edge Cases       | How far to handle cancellation, rejection, or mid-flow abandonment?         |
| Actor Boundaries | Are approver and executor separate? What is each actor's operational scope? |
| Business Rules   | Which steps are automated vs manual? What conditional branches exist?       |

Ask 3-4 questions at a time using multiSelect where appropriate.

### Phase 3: Create

Generate documentation using `erp-kit` CLI. `{APP_ROOT}` is the parent directory where the app will live:

```bash
# Tier 1: Requirements + project structure
# Creates {APP_ROOT}/{APP_NAME}/README.md
npx erp-kit app init {APP_NAME} {APP_ROOT}

# Tier 2: Actors
npx erp-kit app generate doc actors {ACTOR_NAME} -p {APP_ROOT}/{APP_NAME}

# Tier 2: Business Flows
npx erp-kit app generate doc business-flow {FLOW_NAME} -p {APP_ROOT}/{APP_NAME}
```

**Directory structure after init + generate:**

```
{APP_ROOT}/
  {APP_NAME}/
    README.md                                ← Tier 1 (from app init)
    docs/
      actors/{actor-name}.md                 ← Tier 2 (from generate doc actors)
      business-flow/{flow-name}/
        README.md                              ← Tier 2 (from generate doc business-flow)
        story/{actor}--{story-name}.md         ← Tier 2 (from Phase 3b story extraction)
```

**Schema constraints:** See [erp-kit-app-shared/references/schema-constraints.md](../erp-kit-app-shared/references/schema-constraints.md) for H1 heading rules, naming conventions, and requirements structure.

**Business flow diagram:** Use `sequenceDiagram` with actors from "Actors Involved" as participants. Show who initiates each step and the system responses.

**Business flow `## Stories` section:**

Use `- TBD` as a placeholder during flow creation. These will be replaced with actual story links in Phase 3b below.

### Phase 3b: Story Extraction

After creating business flows, extract and create story documentation.

1. **Collect** all business flow docs: glob `<APP_ROOT>/docs/business-flow/*/README.md`
2. **Dispatch story extraction agents** — one Agent per business flow (parallelize if possible). Each agent:

   - Reads the prompt template from [references/story-extraction.md](references/story-extraction.md)
   - Replace `{{APP_NAME}}` with the resolved app name
   - Replace `{{ACTOR_DOCS}}` with the actor doc file paths
   - Replace `{{BUSINESS_FLOW_DOCS}}` with ONLY the single business flow doc for that agent
   - Dispatch the agent with the filled prompt

3. **Scaffold & populate** story docs from agent results:

```bash
# For each story identified
npx erp-kit app generate doc story <flow>/<actor>--<story> -p {APP_ROOT}/{APP_NAME}
```

4. **Link stories** in business flow READMEs: replace `- TBD` placeholders in each flow's `## Stories` section with actual links:

```markdown
- [Story Title](./story/<actor>--<story-name>.md)
```

### Phase 4: Validate

```bash
# NOTE: -p takes {APP_ROOT} (parent directory), NOT {APP_ROOT}/{APP_NAME}.
# generate doc uses -p {APP_ROOT}/{APP_NAME}, but check uses -p {APP_ROOT}.
# Example: if app is at apps/user-management, use -p apps
npx erp-kit app check -p {APP_ROOT}
```

**Expected passing output:** `✓ No violations found` for each doc type that has files. "No matching files found" appears for doc types not yet created (e.g., screens and resolvers at Tier 1-2) — this is normal and not an error.

## Schema Reference

| Schema              | Tier | Output Path                                          |
| ------------------- | ---- | ---------------------------------------------------- |
| `requirements.yml`  | 1    | `README.md`                                          |
| `actors.yml`        | 2    | `docs/actors/<name>.md`                              |
| `business-flow.yml` | 2    | `docs/business-flow/<flow>/README.md`                |
| `story.yml`         | 2    | `docs/business-flow/<flow>/story/<actor>--<name>.md` |

## Next Step

After completing Tier 1-2, use `/erp-kit-app-2-requirements-review` to review documentation quality.
