gt:living-docs

What this skill does

You are a living documentation system. Your job is to keep codebase documentation minimal, accurate, and useful.

## Core Philosophy

**Docs are a search index, not a textbook.**

The code IS the documentation. Doc files exist to help you FIND things fast in a large codebase -- a quick navigation layer, a "where is X?" answering machine, an index that points to code rather than explains it.

**Only document what can't be found easily:**
- Reusable components (API, props, usage) -- keeps code DRY
- Utilities and hooks (what they do, when to use)
- Complex flows (the path through multiple files)
- Non-obvious patterns (things that would take time to figure out)

**Don't document:**
- Implementation details (read the code)
- Obvious things (a Button renders a button)
- One-off code (it's not reusable anyway)

## DRY Documentation (Reusables)

For shared components, hooks, and utilities -- document thoroughly so developers don't re-read source code every time.

**What makes something "reusable":** Lives in a shared package, used by multiple features, has a public API (props, params, returns).

**What reusable docs need:**
- Import statement (exact path)
- Props/params table (type, default, required)
- Usage example (minimal, working)
- Source file location

Without docs, every usage requires: search -> find file -> read source -> understand props -> write code. With docs: context rule fires -> copy example -> done.

## Questions Docs Should Answer

**Navigation:** "Where is X?" -> exact file path
**Usage (reusables):** "How do I use X?" -> props table + example
**Flow:** "How does X work?" -> ASCII diagram showing file path through the system

**Questions docs should NOT answer:**
- "Why was it implemented this way?" -> git history
- "How does this function work internally?" -> read the code

## Operating Modes

### Mode 1: Bootstrap

When documentation is missing:

1. **Scan** - Identify functional areas from directory structure and imports
2. **Chunk** - One doc file per functional area
3. **Write** - Minimal docs with exact file paths
4. **Wire** - Add context rules to CLAUDE.md
5. **Validate** - Run checklist, test rules with sample queries

**Functional areas to detect:** Authentication, Database, UI, Navigation, Features (each major one), Integrations.

**Full bootstrap workflow:**
1. Map the codebase (directories, screens, features, libs, hooks, components, tables/RPCs)
2. Identify functional areas, group related files, name each group, note key files
3. Create one `.md` per area following templates, stay under line limits
4. Wire up CLAUDE.md with preamble + one rule per chunk (5-7 keywords each)
5. Validate all paths, test rules with sample queries, check for keyword conflicts

### Mode 2: Validate

When documentation exists:

1. **Check paths** - Do referenced files still exist?
2. **Check functions** - Do named functions/hooks exist?
3. **Check patterns** - Are documented patterns still used?
4. **Flag drift** - Output a drift report

```text
DRIFT DETECTED in .claude/docs/features/auth.md:
- Line 12: useAuth hook moved from /hooks/useAuth to /lib/auth
- Line 34: loginWithEmail() renamed to signInWithEmail()
- Line 45: File packages/shared/lib/session.ts no longer exists
```

### Mode 3: Update

After code changes, update only affected docs:

1. Identify which doc chunks reference changed files
2. Verify each reference still valid
3. Update only broken references
4. Keep everything else untouched

### Mode 4: Refine

When docs exist but need optimization:

1. **Audit triggers** - Are keywords specific enough? Too generic?
2. **Check activation** - Test if triggers would fire for realistic queries
3. **Validate paths** - Do referenced files still exist?
4. **Optimize content** - Too verbose? Missing quick reference?
5. **Measure coverage** - Undocumented areas?

Output a refinement report:

```text
REFINEMENT ANALYSIS for .claude/CLAUDE.md:

TRIGGER ISSUES:
- "API Routes" rule: keywords too generic ("api", "route")
  → Suggest: Add specific keywords ("endpoint", "REST", "handler", "middleware")
- "Auth" rule: good keywords but missing hook name
  → Suggest: Add "useAuth", "signIn", "signOut"

COVERAGE GAPS:
- No rule for: testing, deployment, error handling
  → Suggest creating: testing.md, deployment.md, error-handling.md

KEYWORD CONFLICTS:
- "component" appears in both "UI Components" and "Design System"
  → Suggest: Split by specificity (button, card → UI; color, theme → Design)

OPTIMIZATION:
- Auth docs: 450 lines (target: 150)
  → Suggest: Split into auth-api.md and auth-ui.md
- Database docs: Missing quick reference
  → Suggest: Add "Drizzle ORM. Run: pnpm db:migrate"

ACTIVATION TEST:
- Query: "How do I add a new button?"
  → Would activate: "UI Components" ✓
- Query: "Update the user table schema"
  → Would activate: None ✗ (missing "table" keyword in Database)
```

### Mode 5: Migrate

When converting old trigger formats to context rules:

1. Extract keywords from old format (`k="..."` or `keywords="..."`)
2. Add 2-3 more specific keywords (function names, file names)
3. Convert "Load:" to "You MUST: Read"
4. Convert "Quick:" to "Quick reference:"
5. Add descriptive section header and `---` separator

**Before (minified):**
```markdown
<t k="auth,login,session">Load: auth.md | Quick summary</t>
```

**Before (verbose):**
```markdown
<context_trigger keywords="auth,login,session">
**Load:** .claude/docs/auth.md
**Quick:** Summary here
</context_trigger>
```

**After:**
```markdown
### Authentication
**When the user asks about:** auth, login, session, useAuth, signIn, signOut
**You MUST:** Read `.claude/docs/auth.md`
**Quick reference:** Summary here
```

## Documentation Structure

```text
.claude/
├── CLAUDE.md              # Main context + rules (load first, always)
├── docs/
│   ├── features/          # Business logic docs (100-200 lines max)
│   ├── systems/           # Technical architecture (50-150 lines max)
│   ├── patterns/          # Code patterns & examples (30-80 lines max)
│   └── integrations/      # External services (50-100 lines max)
└── work/                  # Planning (not loaded by rules)
```

## Doc Chunk Templates

### Feature/Flow Doc (navigation-focused)

```markdown
# [Feature Name]

> [One line: what problem this solves]

## Find It Fast

| Looking for... | Go to |
|----------------|-------|
| Main logic | `path/to/main.ts` |
| Types | `path/to/types.ts` |
| Hook | `packages/shared/hooks/useFeature.ts` |

## Flow Overview

[Only if non-obvious. Show PATH through files, not logic.]

```text
User action -> Screen.tsx -> useFeature() -> rpc_name() -> DB
```

## Entry Points

| Action | Function | Location |
|--------|----------|----------|
| Create X | `createX()` | `lib/feature.ts` |

## Gotchas

- [Only non-obvious things that waste time]
```

### Reusable Component Doc (API-focused)

```markdown
# ComponentName

> [What it does in one line]

## Import

`import { ComponentName } from '@package/shared/ui';`

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | `'primary' \| 'secondary'` | `'primary'` | Visual style |
| onPress | `() => void` | required | Press handler |

## Usage

```tsx
// Basic
<ComponentName onPress={handlePress} />

// With variants
<ComponentName variant="secondary" disabled={loading} />
```

## Compound Components (if applicable)

```tsx
<Card>
  <Card.Header title="Title" />
  <Card.Content>Content here</Card.Content>
  <Card.Footer>
    <Button>Action</Button>
  </Card.Footer>
</Card>
```

## Source

`packages/shared/ui/components/ComponentName.tsx`
```

### Utility/Hook Doc (usage-focused)

```markdown
# useHookName

> [What it does in one line]

## Import

`import { useHookName } from '@package/shared/hooks';`

## API

`const { data, loading, error } = useHookName(params);`

## Parameters / Returns

[Tables with type and description]

## Source

`packages/shared/hooks/useHookName.ts`
```

### Line Guidance (be smart, not rigid)

| T