design-system

Design a System (PRD Authoring)

Writes one PRD per system, one section at a time. Each approved section is written immediately so progress survives compaction or session loss.

Output: design/prd/<system-name>.md

---

Purpose / When to Run

Run when:

• A system has been mapped via /map-systems and is ready for full design
• An existing PRD is missing sections (retrofit mode)
• A reverse-doc needs to be promoted to a full PRD

Inputs

• A system name OR a retrofit <path> argument
• design/concept.md (required)
• design/systems-index.md (recommended)
• design/registry/entities.yaml (if present — cross-system fact registry)
• Existing dependency PRDs in design/prd/
• .claude/docs/technical-preferences.md and docs/framework-reference/<framework>/

Outputs

• design/prd/<system-name>.md — written section by section
• Possibly updated design/registry/entities.yaml
• Possibly updated design/systems-index.md

---

Phase 1: Argument Parsing & Review Mode

Resolve review mode:

1. If --review full|lean|solo present, use it
2. Else read production/review-mode.txt, default lean if absent

If argument starts with retrofit followed by a path, enter retrofit mode:

1. Read the file
2. Identify which of the 8 required sections are present (grep for headings)
3. Required: Overview, User Goal, Detailed Requirements, Edge Cases, Dependencies, Configurable Values, Acceptance Criteria, Accessibility
4. Identify which sections are placeholders ([To be designed] or empty)
5. Print a retrofit summary (sections present vs. missing) and ask: "Fill the [N] missing sections without touching existing ones?"
6. If yes: skip skeleton creation in Phase 3; in Phase 4 only run the section cycle for missing sections; never overwrite existing section content

Otherwise, normalize the system name to kebab-case for the filename.

If no argument and no systems index exists, stop:

"Usage: /design-system <system-name>. No systems index found — run /map-systems first."