# AI-Friendly Product Specs for Distributed Systems

This repository stores human-readable, AI-assisted product specs for distributed-system features. It is structured so PRD authors can move quickly while AI agents can draft, review, and validate specs with stable rules.

## For PRD Authors

Start with one of these prompts:

- `Draft a PRD for accelerating CDC pipeline recovery after partial outages.`
- `Update cdc-recovery-acceleration to add rollback requirements and a migration scenario.`
- `Prepare cdc-recovery-acceleration for review.`
- `Run prd-lint on features/cdc-recovery-acceleration/PRD.md.`

See [.agents/skills/AUTHOR_GUIDE.md](./.agents/skills/AUTHOR_GUIDE.md) for the quick-start guide and [.agents/skills/README.md](./.agents/skills/README.md) for the full skill index.

## Workflow

Use the entry-point skills for authoring work:

1. `prd-draft` creates a new `PRD.md` and `Scenarios.md` from a feature description.
2. `prd-update` updates an existing PRD without redrafting untouched sections.
3. `prd-review` hardens a draft before moving it to `status: review`.
4. `prd-lint` validates structure and traceability on demand.

## Stable ID Conventions

- `JIRA` = optional source ticket field in PRD front matter; may contain one or more explicit ticket-like IDs.
- `FR-###` = Functional requirement or user-visible capability.
- `NFR-###` = Non-functional requirement or operational constraint.
- `INV-###` = Feature-local invariant or safety constraint.
- `SCN-###` = Validation or execution scenario.
- `JTBD-###` = Job to be done.
- `G-###` = Goal.
- `NG-###` = Non-goal.
- `R-###` = Risk.

Keep IDs stable and unique across documents within a feature folder. Do not renumber existing IDs unless you are explicitly normalizing a spec.

## Repository Layout

- `README.md`: top-level authoring and contribution guide.
- `templates/`: canonical starting point for new specs.
- `features/<feature-name>/`: PRDs and scenarios for each feature.
- `shared/`: reusable personas, invariants, security, observability, and compatibility guidance.
- `.agents/skills/`: canonical agent-skill location for author-facing entry points and internal PRD-authoring runbooks.
- `.claude/commands/`: Claude command wrappers that point at the canonical skills.
- `automation/`: review guidance and future checks.

Suggested files under `features/<feature-name>/`:

- `PRD.md`
- `Scenarios.md`

## Contribution Guide

### For PMs

- Start with [templates/PRD.template.md](./templates/PRD.template.md) if you want to write manually, or use `prd-draft` / `prd-update` to scaffold and revise conversationally.
- Use the optional `JIRA` front matter field when the PRD maps to one or more tracked tickets. If present, values must be explicit and non-placeholder.
- Keep requirements atomic, observable, and easy to cross-link.
- Write the Press Release as a real launch artifact with concrete customer outcomes.
- Prefer referencing shared docs for personas and cross-feature constraints instead of duplicating generic text.
- Prefer short, concrete language and examples over vague intent.
- Expect the agent to ask at most one compact question block during drafting, then proceed with explicit assumptions in `draft`.

### For Engineers

- Translate requirements into implementation-oriented architecture and contracts.
- Add explicit `SCN-###` cases for failure handling, ordering, retries, observability, and migration behavior.
- Tie each scenario or contract back to at least one `FR-###` or `INV-###`.
- Keep `FR-###` and `NFR-###` entries in stable label/value form for readability and deterministic parsing.

### AI-Assisted Execution Notes

- Keep required section headers as unnumbered `##` headings matching the PRD template.
- Prefer compact label/value blocks for requirements over sparse spacing or large inventory tables.
- Reference shared personas, invariants, security, observability, and compatibility docs where applicable.
- Prefer deterministic IDs and avoid renumbering existing IDs.

## Review Expectations

- Every PRD must include the required front matter keys: `title`, `feature_id`, `owner`, `status`, `target_release`, `created`, and `last_updated`.
- `JIRA` is optional in `draft`, but if present it must contain explicit ticket-like identifiers rather than placeholders such as `TBD`.
- IDs must be valid and monotonic within each namespace (`FR-001`, `FR-002`, ...).
- Functional and non-functional requirements should have explicit acceptance criteria.
- Cross-links should always be explicit (`FR-001`, `INV-002`, `SCN-004`).

## File Ownership

Place one feature per folder under `features/`. All docs in the folder should share terminology and aligned status updates.