Context Planner

When starting a complex task that requires understanding multiple parts of a codebase, use a two-phase approach:

Phase 1: Orientation

Before reading individual files, run:

repomap . --json

This gives you a curated summary (~500 tokens) including:

• Summary: "Go project, 21 files, 8 docs, 1.9k lines"
• Languages: Primary languages with file counts and complexity
• Entry Points: main.go, index.js, etc.
• Key Modules: Top directories by file count
• Key Docs: Heaviest docs with their top sections
• Doc Map: Quick reference of what's in each doc

Phase 2: Targeted Retrieval

Based on the map:

1. Check entry_points to find where execution starts
2. Check key_modules to find relevant code directories
3. Check key_docs to find documentation for your task
4. Read only those specific files

When to Use This

Use this skill when:

• Starting work on an unfamiliar codebase
• The task mentions multiple components or files
• You need to understand how pieces connect
• The user asks you to "understand" or "explore" the codebase first

Example Flow

1. User: "Add authentication to the API"
2. Run repomap . --json
3. See from output:
   • Entry point: main.go
   • Key module: api/ (12 files)
   • Key doc: docs/AUTH.md (2.1k tokens) with sections ["OAuth", "JWT"]
4. Read api/ and docs/AUTH.md
5. Implement with full context, minimal token burn