Code Analysis Skill
Overview
This skill performs comprehensive code analysis using an intel-first approach - always querying project-intel.mjs before reading full files, achieving 80-95% token savings.
Core principle: Query intel → Verify with MCP → Report with evidence
Announce at start: "I'm using the analyze-code skill to investigate this issue."
Quick Reference
| Phase | Key Activities | Token Budget | Output |
|---|---|---|---|
| 1. Scope | Define objective, bounds, success criteria | ~200 tokens | analysis-spec.md |
| 2. Intel Queries | Search, symbols, dependencies via project-intel.mjs | ~500 tokens | /tmp/intel_*.json |
| 3. MCP Verification | Verify findings with authoritative sources | ~300 tokens | Evidence block |
| 4. Report | Generate CoD^Σ trace report | ~1000 tokens | report.md |
Total: ~2000 tokens vs 20000+ for direct file reading
Templates You Will Use
- @.claude/templates/analysis-spec.md - Scope definition (Phase 1)
- @.claude/templates/report.md - Final analysis report (Phase 4)
- @.claude/templates/mcp-query.md - Optional MCP queries (Phase 3)
Intelligence Tool Guide
- @.claude/shared-imports/project-intel-mjs-guide.md - Complete project-intel.mjs usage
The Process
Copy this checklist to track progress:
Analysis Progress:
- [ ] Phase 1: Scope (analysis-spec.md created)
- [ ] Phase 2: Intel Queries (4 query types executed)
- [ ] Phase 3: MCP Verification (findings verified)
- [ ] Phase 4: Report (CoD^Σ trace complete)
Phase 1: Define Scope
Create analysis-spec.md using template to define:
-
Objective: What question are we answering?
- "Why does LoginForm re-render infinitely?"
- "What causes 500 error on checkout?"
- "Is there circular dependency in auth module?" -
Scope: What's in/out of scope?
- In-Scope: Specific components, files, functions
- Out-of-Scope: Backend, database, third-party APIs -
Success Criteria: How do we know when done?
- "Root cause identified with file:line reference"
- "Complete dependency graph generated"
- "Performance bottleneck located"
Enforcement:
- [ ] Objective is clear and answerable
- [ ] In-scope/out-of-scope explicitly defined
- [ ] Success criteria are testable
Example:
---
spec_id: "analysis-login-rerender"
type: "bug-diagnosis"
---
## Objective
Identify why LoginForm component re-renders infinitely in development.
## Scope
**In-Scope:**
- LoginForm component (src/components/LoginForm.tsx)
- useEffect hooks and dependencies
- State management related to login
**Out-of-Scope:**
- Backend API endpoints
- Database queries
- Production environment
## Success Criteria
- [ ] Root cause identified with specific file:line
- [ ] Fix approach validated with React docs (MCP)
- [ ] CoD^Σ trace shows complete reasoning chain
Phase 2: Execute Intel Queries
CRITICAL: Execute ALL intel queries BEFORE reading any files.
Query 1: Project Overview (if first analysis)
project-intel.mjs --overview --json > /tmp/analysis_overview.json
Purpose: Understand project structure, entry points, file counts
Tokens: ~50
Query 2: Search for Relevant Files
project-intel.mjs --search "<pattern>" --type <filetype> --json > /tmp/analysis_search.json
Purpose: Locate files related to objective
Tokens: ~100
Example:
# For "login form" analysis
project-intel.mjs --search "login" --type tsx --json
# Result: Found LoginForm.tsx, LoginButton.tsx, LoginAPI.ts
Query 3: Symbol Analysis
For each relevant file:
project-intel.mjs --symbols <filepath> --json > /tmp/analysis_symbols_<filename>.json
Purpose: Understand functions/classes without reading full file
Tokens: ~150 per file
Example:
project-intel.mjs --symbols src/components/LoginForm.tsx --json
# Result: LoginForm at line 12, useEffect at line 45, useState at line 15
Query 4: Dependency Tracing
For key files:
# What does this file import?
project-intel.mjs --dependencies <filepath> --direction upstream --json > /tmp/analysis_deps_up.json
# What imports this file?
project-intel.mjs --dependencies <filepath> --direction downstream --json > /tmp/analysis_deps_down.json
Purpose: Understand dependencies and impact
Tokens: ~200 total
Now you know WHERE to look - read only targeted lines using sed -n 'X,Yp'
Token Comparison:
- Reading full LoginForm.tsx (1000 lines): ~3000 tokens
- Intel queries + targeted read (30 lines): ~300 tokens
- Savings: 90%
Enforcement:
- [ ] All 4 query types executed
- [ ] Intel results saved to /tmp/ for evidence
- [ ] No files read before intel queries complete
Phase 3: MCP Verification
Verify findings with authoritative sources:
When to Use Each MCP
| MCP Tool | Use For | Example |
|---|---|---|
| Ref | Library/framework behavior | React hooks, Next.js routing, TypeScript |
| Supabase | Database schema, RLS policies | Table structure, column types |
| Shadcn | Component design patterns | shadcn/ui component usage |
| Chrome | Runtime behavior validation | E2E testing, browser behavior |
MCP Verification Pattern
## Intel Finding
useEffect at src/LoginForm.tsx:45 has dependency [state]
## MCP Verification
**Tool:** Ref MCP
**Query:** ref_search_documentation "React useEffect dependencies"
**Result:** Official React docs confirm dependencies should include all values referenced in effect body
## Comparison
- **Intel shows:** [state]
- **Docs require:** [state, setState, callback]
- **Conclusion:** Missing dependencies confirmed ✓
Enforcement:
- [ ] At least 1 MCP verification for non-trivial findings
- [ ] MCP results documented in Evidence section
- [ ] Discrepancies between intel and MCP flagged
Phase 4: Generate Report
Create comprehensive report using @.claude/templates/report.md
Required: CoD^Σ Trace
Every report MUST include complete reasoning chain:
## CoD^Σ Trace
**Claim:** LoginForm re-renders infinitely due to incomplete useEffect dependencies
**Trace:**
Step 1: → IntelQuery("search login")
↳ Source: project-intel.mjs --search "login" --type tsx
↳ Data: Found LoginForm.tsx, LoginButton.tsx, LoginAPI.ts
↳ Tokens: 100
Step 2: ⇄ IntelQuery("analyze symbols")
↳ Source: project-intel.mjs --symbols src/components/LoginForm.tsx
↳ Data: LoginForm at line 12, useEffect at line 45
↳ Tokens: 150
Step 3: → TargetedRead(lines 40-60)
↳ Source: sed -n '40,60p' src/components/LoginForm.tsx
↳ Data: useEffect(() => { setUser({...user, lastLogin: Date.now()}) }, [user])
↳ Tokens: 100
Step 4: ⊕ MCPVerify("React docs")
↳ Tool: Ref MCP - "React useEffect dependencies"
↳ Data: "Every value referenced inside effect must be in dependency array"
↳ Tokens: 200
Step 5: ∘ Conclusion
↳ Logic: Effect depends on [user] but mutates user → infinite loop
↳ Root Cause: src/components/LoginForm.tsx:47 - incomplete dependency array
↳ Fix: Use functional setState or remove user from dependencies
**Total Tokens:** 550 (vs 3000+ for reading full file)
Report Sections
-
Summary (max 200 tokens)
- Key finding
- Root cause with file:line
- Recommended fix -
CoD^Σ Trace (as shown above)
- Complete reasoning chain
- Token count for each step
- Final token savings calculation -
Evidence
- All intel query results
- MCP verification results
- Targeted file excerpts -
Recommendations
- Specific, actionable fixes
- Implementation guidance
- Testing approach
File Naming
Save as: YYYYMMDD-HHMM-report-<id>.md
Example: 20250119-1430-report-login-infinite-render.md
Enforcement:
- [ ] Report uses template structure
- [ ] CoD^Σ trace complete
- [ ] Every claim has file:line or MCP evidence
- [ ] Recommendations are specific
- [ ] Total report ≤ 1000 tokens when populated
Analysis Type Decision Trees
Tree 1: Bug Diagnosis
User reports error/bug
↓
1. Search for error message/symptom keywords (project-intel.mjs --search)
↓
2. Locate function/component with issue (--symbols)
↓
3. Trace dependencies upstream (what does it use?)
↓
4. Find discrepancy (missing check, wrong data)
↓
5. Verify with MCP if library-related
↓
6. Report with root cause at file:line
Tree 2: Architecture Analysis
User wants to understand system design
↓
1. Get project overview (project-intel.mjs --overview)
↓
2. Identify entry points
↓
3. Trace dependencies from entry points (--dependencies --downstream)
↓
4. Build dependency graph
↓
5. Analyze patterns:
- Circular dependencies?
- Deep nesting?
- Tight coupling?
↓
6. Report with visualization (mermaid diagram)
Tree 3: Performance Analysis
User reports slow operation
↓
1. Search for suspected slow operations (queries, loops)
↓
2. Trace data flow from source to sink
↓
3. Identify bottlenecks:
- N+1 queries?
- Unnecessary re-renders?
- Large data processing?
↓
4. Measure impact (how many times called?)
↓
5. Verify best practices with MCP
↓
6. Report with optimization recommendations
Enforcement Rules
Rule 1: No Naked Claims
❌ Violation:
The login form has a bug in the useEffect.
✓ Correct:
The login form has a bug at src/LoginForm.tsx:45 in the useEffect hook.
Evidence:
- Intel Query: project-intel.mjs --symbols src/LoginForm.tsx
- Result: useEffect at line 45 with dependency [state]
- MCP Verify: Ref MCP confirms dependencies should include all referenced values
- Targeted Read: Lines 40-50 show effect mutates state while depending on it
Rule 2: Intel Before Reading
❌ Violation:
# Agent reads entire file (1000 lines, ~3000 tokens)
cat src/LoginForm.tsx
✓ Correct:
# Agent queries intel first (~50 tokens)
project-intel.mjs --symbols src/LoginForm.tsx --json
# Result: LoginForm at line 12, useEffect at 45
# Read ONLY relevant lines (~100 tokens)
sed -n '40,60p' src/LoginForm.tsx
Token Savings: 96% reduction
Rule 3: MCP for Authority
❌ Violation:
Based on my knowledge, useEffect should include all dependencies.
✓ Correct:
MCP Verification (Ref): ref_search_documentation "React useEffect dependencies"
Official React docs confirm: "Every value referenced inside effect must be in dependency array."
Source: https://react.dev/reference/react/useEffect
Common Pitfalls
| Pitfall | Impact | Solution |
|---|---|---|
| Skipping intel queries | 10-100x token waste | Enforce Phase 2 before any reads |
| Vague conclusions | Not actionable | Always include file:line references |
| No MCP verification | Incorrect assumptions | Verify library behavior with Ref MCP |
| Incomplete CoD^Σ trace | Can't verify reasoning | Document every reasoning step |
Success Metrics
Token Efficiency:
- Intel-first: 500-2000 tokens per analysis
- Direct reading: 5000-20000 tokens
- Target: 80%+ savings ✓
Accuracy:
- Root cause identified: 95%+
- MCP verified: 100% for library issues
Completeness:
- All claims evidenced: 100%
- CoD^Σ trace complete: 100%
When to Use This Skill
Use analyze-code when:
- User reports a bug or error
- User asks "why does X happen?"
- User wants to understand system architecture
- User suspects performance issues
- User needs dependency analysis
Don't use when:
- Simple syntax questions (no analysis needed)
- User wants to write new code (use planning skill)
- User wants to implement a fix (use execution skill)
Related Skills & Commands
- Debugging skill - For specific bug diagnosis workflows
- Planning skill - For creating implementation plans after analysis
- /analyze command - User-invoked analysis (can invoke this skill)
Version
Version: 1.0
Last Updated: 2025-10-19
Owner: Claude Code Intelligence Toolkit
