/init-deep

name: init-deep
description: "Initialize or migrate to nested CLAUDE.md structure for progressive disclosure. Claude auto-loads CLAUDE.md from any directory it reads, enabling true contextual guidance. Triggers on: '/init-deep', 'deep init', 'initialize deeply', 'setup claude deeply', 'refactor claude.md', 'migrate claude.md', 'nested claude', 'progressive disclosure'."
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - Agent
  - AskUserQuestion

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/mo