Model: haiku (templated documentation work)

/document {ID}

• Task has passed testing (

  /test

  returned PASS)
• User has approved the implementation
• Ready to update project documentation

/document 1

/document 001-dashboard-redesign

{ID}

• Numeric ID:

  1

  ,

  2

  ,

  3

  → Looks up in TASKS.md, finds matching task document
• Padded ID:

  001

  ,

  002

  → Same as numeric
• Full filename:

  001-dashboard-redesign

  → Direct file reference

• Feature Documentation Structure - Technical feature docs (see below)
• User Guide Structure - User-facing guides (see below)

docs/features/{FEATURE}.md

• New feature → Create new doc
• Enhancement → Update existing doc
• Significant change → Update relevant sections

docs/guides/{feature}.md

• User-facing feature → Create/update guide
• UI changes → Update screenshots/steps
• New functionality → Add new sections

/CLAUDE.md

• Is this still true based on what was just built?
• Did this task rename a file, change a folder structure, migrate a schema, or replace a pattern?
• If yes → update or remove the stale entry before adding new ones

• Make a mistake without it (wrong pattern, wrong file, wrong approach)
• Waste time discovering it (file location, non-obvious convention)
• Make a decision already made (architecture choice, tool selection)

undefined

• Framework: Next.js 14 App Router (NOT Pages Router)
• Database: Supabase (PostgreSQL) — client at src/lib/supabase/client.ts
• Auth: Supabase Auth — helpers at src/lib/auth.ts
• State: Zustand — stores at src/store/
• Styling: Tailwind CSS

• Components: PascalCase files and exports
• Hooks: use* prefix, always in src/hooks/
• DB queries: always go through src/lib/supabase/ helpers, never raw client calls in components
• {Add when /simplify catches a violation for the second time — that means it's a real pattern}

• Supabase client: src/lib/supabase/client.ts
• Auth helpers: src/lib/auth.ts
• Route middleware: src/middleware.ts
• Environment types: src/types/env.d.ts

• Do not import Supabase client directly in components — use lib/supabase/ helpers
• Do not use

  any

  types — caught by /simplify, will fail quality gate
• {Add only when something was caught by the quality gate or broke in tests}

• Using Zustand over Redux: simpler API for this app's state complexity
• App Router over Pages Router: required for server components
• {Date of decision so agents can judge if it's still current}

---

**Triggers for a CLAUDE.md update after this task:**

| What happened | What to update |
|---------------|----------------|
| New directory created | Project Structure |
| File moved or renamed | Important File Locations |
| Database migration ran | Stack section, any schema notes |
| New package installed | Stack section |
| /simplify caught a repeated violation | Do Not |
| Architecture debate resolved | Architecture Decisions |
| Convention violated and then fixed | Key Conventions |
| Old pattern replaced by new one | Remove old entry, add new |

**Skip the update entirely if:** this task was a small bugfix or UI change that didn't touch architecture, conventions, or file structure.

• docs/learnings/{ID}-{task-name}.md

  — Full retrospective for this task

• LEARNINGS.md

  — Project-wide knowledge base (read by

  /task

  and

  /implement

  on every run)

Status: PRODUCTION Last Updated: {Date}

1. Step 1
2. Step 2

1. Step 1
2. Step 2

• Important detail 1
• Important detail 2

• [Link to related feature]

**Target length:** 200-400 lines

---

{Brief intro sentence}

1. Step with context
2. Step with context

• Tip 1
• Tip 2

1. Step with context

• [Link]

**Target length:** 100-200 lines

---

Date: {date} Quality Gate: PASS on attempt {N} | PASS first try Test cycles: {N} — {0 = passed first time, 1-3 = retried}

1. {Specific, actionable lesson — concrete enough to apply to a future task}
2. {Another lesson if applicable}

• Task type: {feature | bugfix | enhancement}
• Tech areas: {e.g., "Supabase auth", "Next.js App Router", "React state management"}

undefined

Auto-updated by /document after each completed task. Read by /task and /implement before starting any work.

• {Mistake in 5 words}: {What to do instead — 1 sentence} Source: Task #{ID} — {task name} ({date})

**Rules for LEARNINGS.md entries:**
- One entry = one actionable lesson, not a summary of the task
- If the lesson is "nothing went wrong," write a pattern that worked well instead
- Never duplicate — check if a similar lesson already exists before appending
- Keep entries scannable: bold the key phrase, explain in one sentence

---

• Follows template structure
• File paths verified to exist
• API endpoints are accurate
• Schema matches database
• Status set to PRODUCTION
• Last Updated date set
• Under 400 lines

• Follows template structure
• Clear step-by-step instructions
• FAQ answers common questions
• Troubleshooting section included
• Under 200 lines

• Read existing CLAUDE.md before touching it
• Pruned any entries made stale by this task (moved files, changed patterns, replaced approaches)
• Stack updated if new dependency added
• Project Structure updated if directories created or renamed
• Important File Locations updated if key files moved
• Key Conventions updated only if a pattern is now actively enforced
• "Do Not" added only for real mistakes caught by /simplify or tests
• Skipped entirely if task was a small change with no architectural impact

• docs/learnings/{ID}-{task-name}.md

  created
• Quality gate findings documented
• Test cycle count and root cause documented
• Key lesson(s) appended to

  LEARNINGS.md

• No duplicate entries in LEARNINGS.md

• Current state only - Document what exists now
• Accurate file paths - Verify paths exist
• Working examples - Only code that matches production
• Clear user journeys - What users actually do