stack/guides/PRD.md

PRD Requirement Guide (MANDATORY)

This guide defines how requirements are captured before coding.

Hard Rules

1. Before coding begins, docs/PRD.md or docs/PRD.json MUST exist.
2. The PRD is the authoritative requirements source for implementation and testing.
3. The main agent MUST prepare or update the PRD using user input and available project context before implementation starts.
4. The agent MUST NOT invent requirements silently.
5. In steered autonomy mode, best-guess decisions are REQUIRED when needed; each guessed decision MUST be marked with ASSUMPTION: and rationale.

PRD Format

Allowed canonical formats:

1. docs/PRD.md
2. docs/PRD.json

Either format is valid. Both may exist if one is a transformed representation of the other. For markdown PRDs, start from ~/.config/mosaic/templates/docs/PRD.md.template.

Best-Guess Mode

Steered autonomy is the default operating mode.

1. Agent SHOULD fill missing decisions in the PRD without waiting for routine confirmation.
2. Agent MUST mark each guessed decision with ASSUMPTION: and rationale.
3. If user explicitly requests strict-confirmation mode, the agent MUST ask before unresolved decisions are finalized.
4. For high-impact security/compliance/release uncertainty, escalate only if the decision cannot be safely constrained with rollback-ready defaults.

Minimum PRD Content

Every PRD MUST include:

1. Problem statement and objective
2. In-scope and out-of-scope
3. User/stakeholder requirements
4. Functional requirements
5. Non-functional requirements (security, performance, reliability, observability)
6. Acceptance criteria
7. Constraints and dependencies
8. Risks and open questions
9. Testing and verification expectations
10. Delivery/milestone intent

Pre-Coding Gate

Coding MUST NOT begin until:

1. PRD file exists (docs/PRD.md or docs/PRD.json)
2. PRD has required sections
3. Unresolved decisions are captured as explicit ASSUMPTION: entries with rationale and planned validation

Change Control

When requirements materially change:

1. Update PRD first.
2. Then update implementation plan/tasks.
3. Then implement code changes.

Implementation that diverges from PRD without PRD updates is a blocker.