init-deep

What this skill does

# Init Deep Skill

Create a minimal root CLAUDE.md with nested CLAUDE.md files throughout the repository for true progressive disclosure.

## Key Insight

Claude automatically loads CLAUDE.md from any directory it reads. Instead of centralizing documentation in `.claude/docs/`, place CLAUDE.md files directly in relevant directories. When Claude reads `src/api/users.ts`, it also loads `src/api/CLAUDE.md` - contextual guidance exactly when needed.

**Closest Wins:** When multiple CLAUDE.md files apply, the one closest to the file being edited takes precedence. A rule in `src/api/CLAUDE.md` overrides the same topic in root `CLAUDE.md`.

## When This Skill Activates

| Category | Trigger Phrases |
|----------|-----------------|
| **Initialize** | `/init-deep`, `deep init`, `initialize deeply`, `setup claude deeply` |
| **Migrate** | `refactor claude.md`, `migrate claude.md`, `restructure claude` |
| **Structure** | `nested claude`, `progressive disclosure`, `contextual claude` |

## CLI Variants

```
/init-deep              # Update: modify existing + create new where needed
/init-deep --fresh      # Delete all CLAUDE.md files, regenerate from scratch
/init-deep --max-depth=2 # Limit nesting depth (default: unlimited)
```

| Flag | Behavior |
|------|----------|
| (none) | Additive - creates missing, preserves existing |
| `--fresh` | Destructive - deletes all CLAUDE.md, starts clean |
| `--max-depth=N` | Limits nested CLAUDE.md to N levels deep |

## Philosophy: Instruction Budget

Claude has ~150-200 instruction capacity before diminishing returns. A bloated root CLAUDE.md means wasted context on every interaction.

**Solution:** Minimal root + nested CLAUDE.md files that load only when relevant directories are accessed.

### Size Limits (Strict)

| File | Lines | Status |
|------|-------|--------|
| Root CLAUDE.md | 50-150 | Optimal range |
| Root CLAUDE.md | 150+ | Needs refactoring |
| Nested CLAUDE.md | 30-80 | Optimal range |
| Nested CLAUDE.md | 80+ | Too verbose |

**Telegraphic style required.** No verbose explanations. Each line must carry weight.

### Deduplication Rules

Child CLAUDE.md files NEVER repeat parent content:

- If root says "use TypeScript" - children don't repeat it
- If root defines import order - children inherit it
- Child files add domain-specific rules only

**Review Phase Requirement:** Before finalizing, scan all generated CLAUDE.md files for duplicated guidance. Remove duplicates from children, keep in nearest common ancestor.

---

## Directory Scoring System

Not every directory needs a CLAUDE.md. Use weighted scoring to decide.

### Scoring Formula

```
Score = (file_count * 3) + (reference_centrality * 3) + (symbol_density * 1) + (export_count * 1)
```

| Factor | Weight | How to Measure |
|--------|--------|----------------|
| File count | 3x | Number of files in directory |
| Reference centrality | 3x | How many imports/exports reference this dir |
| Symbol density | 1x | Functions, classes, types defined |
| Export count | 1x | Public API surface |

### Score Thresholds

| Score | Action |
|-------|--------|
| >15 | Definitely gets CLAUDE.md |
| 8-15 | Only if distinct domain (tests, api, components) |
| <8 | Parent CLAUDE.md covers it |

### Quick Heuristics

When scoring isn't practical, use these rules:

| Directory | Create CLAUDE.md? | Reason |
|-----------|-------------------|--------|
| tests/ | YES | Testing patterns are domain-specific |
| src/components/ | YES | Component patterns are specialized |
| src/api/ | YES | API design patterns are critical |
| src/hooks/ | MAYBE | If project has custom hooks |
| src/utils/ | MAYBE | If utility patterns are non-obvious |
| src/services/ | MAYBE | If services have specific patterns |
| src/ | MAYBE | For general coding conventions |
| scripts/ | RARELY | Only if complex build system |
| node_modules/ | NEVER | Not your code |
| dist/ | NEVER | Generated code |

---

## Two Operating Modes

### Mode 1: Fresh Project (No CLAUDE.md)

Create minimal root + nested structure from scratch.

### Mode 2: Existing CLAUDE.md

Analyze, categorize, and migrate content to nested CLAUDE.md files.

---

## Workflow

### Phase 1: Discovery

**Goal:** Understand current state and scope.

**Actions:**

1. Check if root CLAUDE.md exists
2. Scan for common directories that should have nested CLAUDE.md
3. Check for existing nested CLAUDE.md files
4. Detect if `.claude/docs/` exists (old pattern to migrate)
5. Calculate directory scores for prioritization

**Dynamic Agent Scaling:**

| Condition | Action |
|-----------|--------|
| Files >100 | Spawn additional Explore agents |
| Depth >=4 | Increase exploration scope |
| Multiple languages | Spawn language-specific analysis |

**Concurrent Execution:** Launch all exploration agents in parallel (one message, multiple Task calls). Do not wait for one to finish before starting others.

**Directory Detection Patterns:**

```
src/           # Source code root
tests/         # Test files
test/          # Alternative test directory
lib/           # Library code
api/           # API layer (may be under src/)
components/    # UI components
hooks/         # React/custom hooks
utils/         # Utility functions
services/      # Service layer
scripts/       # Build/dev scripts
packages/      # Monorepo packages
apps/          # Monorepo apps
```

**Nested directory patterns (check inside src/):**

```
src/api/
src/components/
src/hooks/
src/utils/
src/services/
src/lib/
src/routes/
src/pages/
src/stores/
src/models/
```

**Detection Script:**

```bash
# Find directories that should have CLAUDE.md
for dir in tests test src lib api components hooks utils services scripts packages apps; do
  if [ -d "$dir" ]; then
    echo "FOUND: $dir/"
  fi
done

# Check src/ subdirectories
if [ -d "src" ]; then
  for subdir in api components hooks utils services lib routes pages stores models; do
    if [ -d "src/$subdir" ]; then
      echo "FOUND: src/$subdir/"
    fi
  done
fi
```

---

### Phase 2: Interview

**Goal:** Gather essential project info.

**For Fresh Projects, Ask:**

**Question 1: Project Description**
```
What does this project do? (One sentence)

Example: "A CLI tool for managing Kubernetes deployments"
```

**Question 2: Package Manager**
```
Which package manager does this project use?

Options:
- npm (default, will not be documented)
- pnpm
- yarn
- bun
- none (not a JS/TS project)
```

**Question 3: Non-Standard Commands**
```
Any build, test, or lint commands that differ from standard?

Leave blank if using standard commands (npm test, npm run build).
Only specify if different, e.g., "pytest -v" or "make release"
```

**Question 4: Nested CLAUDE.md Selection**
```
I detected these directories. Which should have their own CLAUDE.md?

Detected:
- [x] tests/
- [x] src/components/
- [x] src/api/
- [ ] src/utils/
- [ ] scripts/

Select all that would benefit from contextual guidance.
(Default: tests/ and any domain-specific src/ directories)
```

**For Existing CLAUDE.md Migration, Ask:**

```
Found existing CLAUDE.md ({N} lines). Options:

1. Analyze and migrate - Extract content to nested CLAUDE.md files
2. Replace - Create fresh minimal structure (backup original)
3. Cancel - Keep existing structure
```

---

### Phase 3: Analysis (Existing CLAUDE.md Only)

**Goal:** Categorize existing content for migration.

**Metrics to Calculate:**

| Metric | How | Threshold |
|--------|-----|-----------|
| Line Count | Total non-empty lines | >150 = needs migration |
| Instruction Count | Count MUST/NEVER/ALWAYS/should | >30 = instruction overload |
| Hardcoded Paths | Regex for file paths | >10 = staleness risk |
| Sections | Count ## headers | >8 = fragmented |

**Content Categorization:**

Map existing content to potential nested locations:

| Content Type | Destination |
|--------------|-------------|
| Project description, tech stack | Root CLAUDE.md |
| Package manager, build commands | Root CLAUDE.md |
| Task-to-location mapping | Root CLAUDE.