---
description: Update DESIGN.md with architecture decisions — the single source of truth for project design
argument-hint: [topic or decision to document]
---

# /doc — Design Documentation

DESIGN.md is the single source of truth for **why** the project is built the way it is. These rules are absolute.

---

## Structure

DESIGN.md has exactly three sections — no others:

```markdown
## Architecture
[one paragraph]

## Decisions
[one entry per non-obvious choice]

## Constraints
[external impositions only]
```

---

## Rules

- **100-line hard cap.** If at or near the limit, delete or consolidate before adding.
- **Architecture:** one paragraph only — never bullets. Describes structural decisions that constrain everything else.
- **Decisions:** each entry ≤ 5 lines, format:
  ```
  ### <topic>
  - **Chose:** <what>
  - **Why:** <reason>
  - **Rejected:** <alternative> — <one-line reason>
  ```
- **Constraints:** anything imposed externally (platform, dependency, environment). Anything you chose goes in Decisions.
- **No dates, versions, "as of", or progress notes.** Ever.
- **Delete entries when the decision is no longer live** (code is gone or constraint lifted).
- Git is the history. DESIGN.md reflects current code only.

---

## When Invoked as `/doc`

**If `$ARGUMENTS` describes a decision or topic:**
1. Read DESIGN.md
2. Determine section: Architecture update, new/updated Decision, or Constraint
3. If at or near 100 lines, identify and remove the stalest entry first
4. Add or update the entry following the rules above
5. Write the updated DESIGN.md

**If no argument provided — audit mode:**
- Read DESIGN.md and report:
  - Line count vs 100-line cap
  - Rule violations: entries over 5 lines, unapproved sections, dates found, Architecture using bullets
  - Potentially stale entries (decisions about code that may no longer exist)