# Requirements Lifecycle

Requirements files capture user-centered product intent before implementation chunks are created.

Artifact filenames follow `ai/standards/artifact-naming.md`.

## Lifecycle Folders

- `ai/requirements/drafts`: rough ideas and early requirements drafts.
- `ai/requirements/active`: requirements currently being refined or reviewed.
- `ai/requirements/approved`: requirements that passed review and are ready for chunk planning.
- `ai/requirements/completed`: requirements that have been planned into chunks or superseded by completed work.

## File Format

Requirements files follow `ai/standards/requirements.md`.
Review and approval use `ai/standards/requirements-gates.md`.

Use metadata:

```md
---
Status: Draft | Active | Approved | Completed
Owner Role: Requirements Intake | Requirements Review | Chunk Planner | Orchestrator
Created: YYYY-MM-DDTHH:mm:ss.sssZ
Approved:
Depends On:
Validation:
---
```

Use these core sections:

- `## Raw Idea`
- `## User Perspective`
- `## User Workflows`
- `## Functional Requirements`
- `## Non-Functional Requirements`
- `## Data / Model Requirements`
- `## Permissions / Auth Requirements`
- `## UI / UX Requirements`
- `## Out Of Scope`
- `## Assumptions`
- `## Open Questions`
- `## Acceptance Criteria`
- `## Runtime Smoke Expectations`
- `## Risks`
- `## Requirements Intake Notes`
- `## Requirements Review`
- `## Chunk Plan`
- `## Pass History`

## Workflow

1. Requirements Intake accepts a rough idea and creates or revises a draft.
2. Requirements Review checks whether the draft is complete enough to build using `ai/standards/requirements-gates.md`.
3. If review is `BLOCKED`, intake revises the requirements or asks the user focused questions.
4. If review is `PASS`, approve the file into `ai/requirements/approved`.
5. Chunk Planner converts approved requirements into ordered chunk drafts.
6. Orchestrator runs approved chunks through Developer -> QA loops.

## Lifecycle Helpers

Create requirements:

```sh
ai/commands/new-requirements.sh <slug> [draft|active]
```

Inspect state:

```sh
ai/commands/requirements-state.sh
ai/commands/requirements-state.sh ai/requirements/drafts/requirements-000001-example.md
```

Approve requirements after Requirements Review PASS:

```sh
ai/commands/approve-requirements.sh ai/requirements/active/requirements-000001-example.md
```

Complete requirements after chunk planning or when superseded:

```sh
ai/commands/complete-requirements.sh ai/requirements/approved/requirements-000001-example.md
```

Helpers only operate inside `ai/requirements/drafts`, `ai/requirements/active`, `ai/requirements/approved`, and `ai/requirements/completed`.

## Relationship To Chunks

Requirements do not replace chunks. Requirements describe what should be built and why; chunks describe small, testable implementation steps.

When requirements are approved, chunk planning should produce draft chunks under `ai/chunks/drafts` or text ready to create those chunks. Each chunk should reference the requirement it came from in `Depends On` or the chunk body.

## Pass History

Keep `## Pass History` chronological. Use it to preserve intake, review, and planning decisions without overwriting earlier passes.