/document - Documentation Agent

Usage:
  /document {ID}                     Update docs for a task
  /document -h, --help               Show this help message
  /document -v, --version            Show version

Arguments:
  {ID}    Task ID (number) or task filename (e.g., 001-auth-jwt)

Creates/Updates:
  - docs/features/{feature}.md       Technical documentation
  - docs/guides/{feature}.md         User guides (if user-facing)
  - CLAUDE.md                        Project patterns (if needed)

Examples:
  /document 1                        # Document task #1
  /document 001-auth-jwt             # Using task filename

Next: /ship {ID}

Workflow Skills v1.5.1
https://github.com/eljun/workflow-skills

/document {ID}
       ↓
1. Resolve task ID → find task document
2. Read task document for context
3. Check Automation field (manual | auto)
4. Read test report for verification
5. Update/create feature documentation
6. Update/create user guide (if user-facing)
7. Update CLAUDE.md files if needed
8. Write retrospective → update LEARNINGS.md
9. Move task to "Approved" in TASKS.md
       ↓
┌─── Automation Mode? ───┐
│                        │
▼ Manual                 ▼ Auto
Notify user              Invoke /ship {ID}
Ready for /ship

Documentation complete: #{ID} - {Task Title}

Updated files:
- docs/features/{feature}.md
- docs/guides/{feature}.md

[AUTO] Spawning /ship with haiku model...

docs/task/{ID}-{task-name}.md        - Implementation details
docs/testing/{ID}-{task-name}.md     - Test results & verification

# {Project Name}

## Stack
{Only what's non-obvious or frequently relevant to agents}
- 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

## Project Structure
{Update this when directories are created, renamed, or removed}
src/
  app/           # App Router pages and layouts
  components/
    ui/          # Primitive components (Button, Input, Modal)
    features/    # Feature-specific components
  lib/           # Integrations (supabase/, stripe/, etc.)
  hooks/         # Custom React hooks
  store/         # Zustand stores

## Key Conventions
{Only conventions that are actively enforced or non-obvious}
- 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}

## Important File Locations
{Files that agents always need to find — update when files move}
- 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
{Hard rules — each one from a real mistake, not speculation}
- 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}

## Architecture Decisions
{Decisions made so future agents don't re-open the debate}
- 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}

# Feature: {Feature Name}

> **Status:** PRODUCTION
> **Last Updated:** {Date}

## Overview

{Brief 2-3 sentence description}

---

## User Journey

### For Customers
1. Step 1
2. Step 2

### For Business Owners
1. Step 1
2. Step 2

---

## Architecture

### File Structure
{Accurate file tree - VERIFY paths exist}

### Database Schema
{SQL with comments, if applicable}

### API Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|

---

## Implementation Details

### Key Components
| Component | Location | Purpose |
|-----------|----------|---------|

### Technical Notes
- Important detail 1
- Important detail 2

---

## Related Features
- [Link to related feature]

# {Feature Name} Guide

> {Brief intro sentence}

## Quick Start
{1-2 paragraph overview}

---

## For Customers

### How to {Primary Action}
1. Step with context
2. Step with context

### Tips
- Tip 1
- Tip 2

---

## For Business Owners

### How to {Admin Action}
1. Step with context

### Settings
| Setting | Location | What it does |
|---------|----------|--------------|

---

## FAQ

**Q: Question?**
A: Answer.

---

## Troubleshooting

**Issue:** Description
**Solution:** How to fix

---

## Related Guides
- [Link]

# Retrospective: #{ID} - {Task Title}

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

## Plan vs Reality

### What was planned
{2-3 sentences from task doc Overview — what was the intent}

### What was delivered
{What actually changed — from git diff or Implementation Notes}

### Deviations from plan
{None | Minor: {description} | Medium: {description}}

## What the Quality Gate Caught
{Issues /simplify flagged — if none, write "None — implementation met standards on first pass"}

These are direct lessons: if the quality gate caught something, future agents doing similar work should know to avoid it upfront.

## What Tests Revealed
{What failed on first test run and why — if tests passed first time, write "Tests passed on first run"}

Root cause of any test failures is the most valuable lesson here.

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

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

# Project Learnings

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

---

## Architecture & Decisions

| Decision | Rationale | Date | Task |
|----------|-----------|------|------|

---

## Established Coding Patterns

{Patterns that have proven to work in this codebase}

---

## Common Mistakes to Avoid

{Things the quality gate or tests caught — don't repeat these}

---

## Testing Patterns

{What works and what doesn't when testing this project}

---

## Tech Stack Notes

{Non-obvious things about the stack that future agents should know}

## Common Mistakes to Avoid

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

## Approved

| ID | Task | Task Doc | Feature Doc | Test Report | Approved |
|----|------|----------|-------------|-------------|----------|
| 1 | Quick Actions Redesign | [001-quick-actions.md](docs/task/001-quick-actions.md) | [feature](docs/features/...) | [001-quick-actions.md](docs/testing/001-quick-actions.md) | Jan 25 |

Documentation updated for: #{ID} - {Task Title}

Updated files:
- docs/features/{feature}.md (created/updated)
- docs/guides/{feature}.md (created/updated)
- CLAUDE.md (if updated)
- docs/learnings/{ID}-{task-name}.md (retrospective)
- LEARNINGS.md (lesson appended)

Task moved to "Approved" in TASKS.md

Next Steps:
  /ship {ID}              # e.g., /ship 1
  /ship {ID}-{task-name}  # e.g., /ship 001-auth-jwt

Documentation updated for: #{ID} - {Task Title}

Updated files:
- docs/features/{feature}.md (created/updated)
- docs/guides/{feature}.md (created/updated)
- CLAUDE.md (if updated)
- docs/learnings/{ID}-{task-name}.md (retrospective)
- LEARNINGS.md (lesson appended)

Task moved to "Approved" in TASKS.md

[AUTO] Spawning /ship with haiku model...