documentation-management

What this skill does

# Documentation Management

Maintain clean, useful documentation by following clear guidelines for what to create, how to name it, where to put it, and when to archive or delete it.

## When to Use This Skill

Invoke this skill when:

### ✅ Creating Documentation
- About to create a new .md file
- Completing an analysis or audit
- Documenting a decision or design
- Uncertain if something should be documented

### ✅ Maintaining Documentation
- Reviewing existing docs for relevance
- Deciding whether to archive or delete
- Organizing documentation structure
- Creating index/README files

### ✅ Meta Questions
- "Should I document this?"
- "Where does this doc belong?"
- "Is this still useful or just clutter?"
- "What should I name this file?"

## The Problem: Documentation Clutter

### What Happens Without Clear Policies

```
Timeline:
T0: Create ANALYSIS.md during investigation
T1: Create FIX_PLAN.md with proposed changes
T2: Implement fixes, create skills encoding patterns
T3: Create ANOTHER_ANALYSIS.md for different issue
T4: Months later...
  ↓
docs/ directory has 20+ files
  ↓
Generic names: ANALYSIS.md, AUDIT.md, PLAN.md
No dates, no clear relevance
  ↓
Can't tell what's current vs historical
Can't tell what's useful vs clutter
  ↓
New developers overwhelmed
Nobody links to these docs
Nobody maintains them
```

**Result:** Documentation becomes write-only. Nobody reads it, nobody trusts it.

## Solution: Documentation Policy

### Three Core Principles

1. **Be ruthless** - If you wouldn't link to it in README, delete it
2. **Be explicit** - Names and structure should make purpose obvious
3. **Extract to skills** - Repeatable patterns become skills, then delete source docs

## Document Types & Decision Tree

### Type 1: Active Reference Guides

**Purpose:** Timeless reference documentation that developers actively use

**Characteristics:**
- Referenced frequently during development
- Explains HOW to do something
- Doesn't become outdated (or gets updated when it does)
- Would link to it in project README

**Naming:** `{topic}-guide.md`

**Location:** `docs/guides/`

**Lifecycle:** Keep forever, update as needed

**Test:** "Would a new developer need this to work on the project?"

### Type 2: Architecture Documentation

**Purpose:** Explain system design, structure, and "why" decisions

**Characteristics:**
- Explains WHY the system works this way
- Documents design decisions and trade-offs
- Helps understand the big picture
- Relatively stable (architecture doesn't change often)

**Naming:** `{COMPONENT}_ARCHITECTURE.md` or `{COMPONENT}_DESIGN.md`

**Location:** `docs/architecture/`

**Lifecycle:** Keep forever, update when architecture changes

**Test:** "Does this explain why the system is structured this way?"

### Type 3: Architecture Decision Records (ADRs)

**Purpose:** Document important decisions to prevent re-litigation

**Characteristics:**
- Point-in-time decision with context
- Answers: What was decided? Why? What were alternatives?
- Immutable (never updated, new ADR if decision changes)
- Dated to show when decision was made

**Naming:** `YYYY-MM-DD-{decision-title}.md`

**Location:** `docs/decisions/`

**Lifecycle:** Keep forever (shows evolution of thinking)

**Test:** "Would this prevent someone from proposing we re-do something we already tried?"

**Template:**
```markdown
# {Title of Decision}

**Date:** YYYY-MM-DD
**Status:** Accepted | Superseded by ADR-XXX
**Context:** What problem are we solving?
**Decision:** What did we decide to do?
**Alternatives Considered:**
- Option A: Pros/Cons
- Option B: Pros/Cons
**Consequences:** What are the implications?
**References:** Links to related issues, PRs, discussions
```

### Type 4: Skills

**Purpose:** Encode repeatable patterns and workflows

**Characteristics:**
- Actionable, step-by-step guidance
- Repeatable workflow
- Clear triggers for when to use
- Checklists and decision trees

**Naming:** `{descriptive-name}/SKILL.md`

**Location:** `.claude/skills/{skill-name}/`

**Lifecycle:** Keep forever, update as patterns evolve

**Test:** "Will I do this task more than once? Does it have clear steps?"

### Type 5: Historical Audits/Analysis

**Purpose:** Document completed investigations and fixes

**Characteristics:**
- Point-in-time snapshot of a problem
- "Here's what we found and fixed"
- Useful context for understanding why code exists
- BUT: Often superseded by skills or code comments

**Naming:** `YYYY-MM-DD-{audit-name}.md`

**Location:** `docs/archive/` (if kept at all)

**Lifecycle:**
- **Option A:** Delete if lessons are encoded in skills
- **Option B:** Archive with date if decision context is valuable

**Test:** "Does this provide context that isn't captured elsewhere?"

### Type 6: Working Documents

**Purpose:** Temporary analysis during active development

**Characteristics:**
- Created during investigation
- Helps organize thoughts
- Not meant to be permanent
- Serves as input to final docs (skills, ADRs, guides)

**Naming:** `YYYY-MM-DD-WIP-{topic}.md` or just work in memory/notes

**Location:** Root directory (temporary) or don't create at all

**Lifecycle:**
- **Delete immediately** after final doc is created
- **Never commit** if just for organizing thoughts
- **Convert** to skill/ADR/guide, then delete working doc

**Test:** "Will this still be useful a month from now?" (If no, delete it)

### Type 7: Session Tracking Documents

**Purpose:** Persistent tracking of active work and deferred ideas across sessions

There are TWO tracking locations - project-specific and cross-project:

#### Project-Specific Tracking (`docs/tracking/`)

For work tied to a specific project:

**Files:**
- `docs/tracking/ACTIVE.md` - Current work in progress for THIS project
- `docs/tracking/BACKLOG.md` - Deferred ideas for THIS project

**Use when:**
- Bug fixes, features, refactoring for this codebase
- Project-specific TODOs and technical debt
- Items that only make sense in this project's context

#### Cross-Project Tracking (`~/git/hh-meta/tracking/`)

For ideas, notes, and backlog that span projects or aren't project-specific:

**Files:**
- `tracking/IDEAS.md` - Future features, exploration ideas, "what if" thoughts
- `tracking/BACKLOG.md` - Deferred work with context for later pickup
- `tracking/PROJECTS.md` - Active projects overview and status
- `tracking/NOTES.md` - Learnings, decisions, patterns discovered

**Use when:**
- Idea applies to multiple projects
- General learning or pattern worth remembering
- Meta-level tracking (project statuses, cross-cutting concerns)
- Not sure which project it belongs to

#### Decision: Project vs Cross-Project

```
Is this tied to a specific project's codebase?
  ↓ YES → Project tracking (docs/tracking/)
  ↓ NO
Is this a general idea, learning, or cross-cutting concern?
  ↓ YES → Cross-project tracking (~/git/hh-meta/tracking/)
  ↓ UNCLEAR → ASK THE USER where it should go
```

**IMPORTANT:** When unclear whether something is project-specific or cross-project, ASK the user: "Should I track this in the project's docs/tracking/ or in hh-meta for cross-project visibility?"

**Characteristics:**
- Persistent across sessions (unlike TodoWrite which is ephemeral)
- Provides continuity when resuming work
- Separates "what we're doing" from "what we might do"
- Cross-project tracking is backed up to GitHub (private repo)

**Lifecycle:** Permanent files, content updated as work progresses

**Test:** "Is this tracking active work or deferred ideas?" (If yes, use tracking docs)

## The Decision Tree

### Should I Create Documentation?

```
New information/analysis → Should this be documented?
  ↓
Q1: Is this a repeatable pattern/workflow?
  ↓ YES
  → Create SKILL
  → Delete working notes

  ↓ NO
Q2: Is this explaining HOW to do something?
  ↓ YES
  → Create GUIDE (docs/guides/)
  → Permanent

  ↓ NO
Q3: Is this explaining WHY the system is designed this way?
  ↓ YES
  → Create ARCHITECTURE doc (docs/architecture/)
  → Permanent

  ↓ NO
Q4: Is this