Why Stages?

The SDLC pipeline produces documents in stages because each stage catches problems that later stages would bury. Here is why each element exists.

Gap Surfacing

Drafts miss things. A user requirements conversation might describe the happy path but never discuss what happens when an external API is down, or when a user enters invalid data, or when the database is full.

Every document stage has blind spots. The finalize step applies a gap checklist — personas, error states, non-functional requirements, edge cases — and flags what was missed. It does not silently fill gaps. It warns and proceeds, so the human reviewer sees exactly what was assumed.

Catching gaps in documents is cheaper than catching them in code. A missing error handler discovered during a design review is a one-line addition to the PDR. The same gap discovered during implementation is a refactor.

Traceability Chains

User stories get US-NNN IDs. Non-functional requirements get NFR-NNN IDs. PDR sections reference user story IDs. Plan tasks reference PDR sections. The chain is unbroken from user need to design decision to implementation task.

Why this matters: when a requirement changes, you can trace downstream to find every design element and task affected. When a task seems unnecessary, you can trace upstream to find the requirement it serves. Nothing exists without a reason, and every reason is traceable.

Phased Execution

The plan breaks work into ordered phases, each independently shippable. Each phase ends in a working state — no phase leaves the system broken. One commit per phase creates a clean history where every commit is a functional checkpoint.

Phases are ordered by risk and dependency: prove infrastructure first, build content later. If Phase 0 (scaffold and deploy pipeline) fails, you learn that before writing any feature code. If Phase 1 (layout and navigation) has responsive issues, you fix them before adding content pages.

Human-in-the-Loop

AI assists at every stage but humans review at every transition. The workflow is AI-assisted, not AI-autonomous.

draft-* commands extract and structure conversation content — they do not invent requirements or design decisions. gen-* commands make engineering decisions but flag assumptions explicitly so the reviewer can accept or override them. finalize adds what the drafts missed but marks every addition visibly.

The pipeline assumes that a human is reviewing each document before moving to the next stage. The document format is designed for human readability, not just machine consumption.