discovery-first
Use pre-computed discovery files at .claude/state/ for codebase inventory questions. Triggers on component, hook, schema, form, type, inventory, what exists, list all, how many. Saves 90%+ tokens vs source scanning.
When & Why to Use This Skill
The Discovery-First skill optimizes Claude's performance on large codebases by prioritizing pre-computed inventory files over manual source code scanning. By utilizing structured JSON data in the .claude/state directory, it reduces token consumption by over 90% and accelerates response times for architectural and inventory queries, ensuring the agent remains efficient and cost-effective during complex development tasks.
Use Cases
- Case 1: Rapidly listing all React components, custom hooks, or UI forms within a specific feature module without scanning the entire directory.
- Case 2: Identifying all TypeScript types and database schemas used across a project to understand data structures without hitting token limits.
- Case 3: Mapping call graphs and component dependencies using pre-indexed state files for faster architectural analysis and debugging.
- Case 4: Performing high-level codebase audits and inventory checks (e.g., 'How many forms exist?') while maintaining a slim context window for long-running conversations.
| name | discovery-first |
|---|---|
| description | Use pre-computed discovery files at .claude/state/ for codebase inventory questions. Triggers on component, hook, schema, form, type, inventory, what exists, list all, how many. Saves 90%+ tokens vs source scanning. |
Discovery-First Skill
Purpose
ALWAYS read discovery files before scanning source code for inventory questions.
When This Triggers
- "What components exist in contacts?"
- "List all hooks in the codebase"
- "What schemas are used for opportunities?"
- "How many forms exist?"
- "Which types are defined?"
- "What calls useContactData?"
Discovery Files Location
| Question Type | Read This First |
|---|---|
| Components | .claude/state/component-inventory/{feature}.json |
| Hooks | .claude/state/hooks-inventory.json |
| Schemas | .claude/state/schemas-inventory/{feature}.json |
| Forms | .claude/state/forms-inventory.json |
| Types | .claude/state/types-inventory/{feature}.json |
| Call Graph | .claude/state/call-graph-inventory/{feature}.json |
Chunk Discovery Pattern
- Read
manifest.jsonin the inventory directory first - Find the chunk that contains the feature you need
- Read only that chunk (e.g.,
contacts.json)
Why This Matters
| Method | Token Cost | Speed |
|---|---|---|
| Discovery JSON | ~30KB | < 2 sec |
| Source scanning | ~500KB | 5-15 sec |
| Savings | 94% | 5x faster |
Required Behavior
- DO: Read
.claude/state/JSON files first - DO: Use manifest.json to find the right chunk
- DON'T: Grep/Glob src/atomic-crm for inventory questions
- DON'T: Use Task/Explore agent for basic component/hook listing
- DON'T: Read individual source files when inventory answers the question
Example: Correct Approach
Question: "What hooks does ContactList use?"
Wrong approach:
Grep("use.*=", "src/atomic-crm/contacts/ContactList.tsx")
Read("src/atomic-crm/contacts/ContactList.tsx")
Correct approach:
Read(".claude/state/component-inventory/contacts.json")
→ Find ContactList entry → Read hooks array
Freshness
Discovery files are auto-regenerated on pre-commit via .husky/pre-commit.
If data seems stale, run: just discover