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

---

Workflow Files

Detailed Workflows:

• @.claude/skills/analyze-code/workflows/analysis-workflow.md - Complete Phases 1-4 (scope, intel queries, MCP verification, report generation)

Reference Materials:

• @.claude/skills/analyze-code/references/decision-trees.md - 3 analysis type decision trees (bug diagnosis, architecture, performance)
• @.claude/skills/analyze-code/references/enforcement-rules.md - 3 non-negotiable rules (no naked claims, intel before reading, MCP for authority)
• @.claude/skills/analyze-code/references/failure-modes.md - 5 common failures with solutions

---

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 (Overview)

See: @.claude/skills/analyze-code/workflows/analysis-workflow.md for complete details

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:

1. 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?"

2. Scope: What's in/out of scope?

   • In-Scope: Specific components, files, functions
   • Out-of-Scope: Backend, database, third-party APIs

3. Success Criteria: How do we know when done?

   • "Root cause identified with file:line reference"
   • "Complete dependency graph generated"
   • "Performance bottleneck located"

Enforcement Checklist:

• Objective is clear and answerable
• In-scope/out-of-scope explicitly defined
• Success criteria are testable

---

Phase 2: Execute Intel Queries

CRITICAL: Execute ALL intel queries BEFORE reading any files.

4 Required Query Types:

1. Project Overview (if first analysis in session):

   project-intel.mjs --overview --json > /tmp/analysis_overview.json
   

   Purpose: Understand project structure, entry points, file counts Tokens: ~50

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

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

4. Dependency Tracing:

   # 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

Token Comparison:

• Reading full LoginForm.tsx (1000 lines): ~3000 tokens
• Intel queries + targeted read (30 lines): ~300 tokens
• Savings: 90%

Enforcement Checklist:

• All 4 query types executed
• Intel results saved to /tmp/ for evidence
• No files read before intel queries complete

See: @.claude/skills/analyze-code/workflows/analysis-workflow.md for complete query examples

---

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
[What intelligence queries revealed]

## MCP Verification
**Tool:** [Which MCP tool]
**Query:** [Exact query executed]
**Result:** [What authoritative source says]

## Comparison
- **Intel shows:** [From project-intel.mjs]
- **Docs require:** [From MCP verification]
- **Conclusion:** [Agreement or discrepancy]

Enforcement Checklist:

• At least 1 MCP verification for non-trivial findings
• MCP results documented in Evidence section
• Discrepancies between intel and MCP flagged

See: @.claude/skills/analyze-code/workflows/analysis-workflow.md for complete verification examples

---

Phase 4: Generate Report

Create comprehensive report using @.claude/templates/report.md

Required: CoD^Σ Trace

Every report MUST include complete reasoning chain with symbolic operators:

## CoD^Σ Trace

**Claim:** [Your conclusion with file:line reference]

**Trace:**

Step 1: → IntelQuery("search ") ↳ Source: project-intel.mjs --search "" --type ↳ Data: [What was found] ↳ Tokens: [Token count]

Step 2: ⇄ IntelQuery("analyze symbols") ↳ Source: project-intel.mjs --symbols ↳ Data: [Functions/classes found with line numbers] ↳ Tokens: [Token count]

Step 3: → TargetedRead(lines X-Y) ↳ Source: Read (lines X-Y only) ↳ Data: [Relevant code excerpt] ↳ Tokens: [Token count]

Step 4: ⊕ MCPVerify("") ↳ Tool: - "" ↳ Data: [What authoritative source says] ↳ Tokens: [Token count]

Step 5: ∘ Conclusion ↳ Logic: [Reasoning from data to conclusion] ↳ Root Cause: : - [What's wrong] ↳ Fix: [How to resolve]

**Total Tokens:** [Sum] (vs [baseline] for reading full files)
**Savings:** [Percentage]

**Report Sections:**

1. **Summary** (max 200 tokens): Key finding, root cause with file:line, recommended fix
2. **CoD^Σ Trace** (as shown above): Complete reasoning chain, token counts, savings
3. **Evidence**: All intel query results, MCP verification, targeted file excerpts
4. **Recommendations**: Specific fixes, implementation guidance, testing approach

**File Naming:** `YYYYMMDD-HHMM-report-<id>.md`

**Enforcement Checklist:**
- [ ] Report uses template structure
- [ ] CoD^Σ trace complete
- [ ] Every claim has file:line or MCP evidence
- [ ] Recommendations are specific
- [ ] Total report ≤ 1000 tokens when populated

**See:** @.claude/skills/analyze-code/workflows/analysis-workflow.md for complete report examples

---

## Decision Trees for Different Analysis Types

**See:** @.claude/skills/analyze-code/references/decision-trees.md

**Summary:**

- **Tree 1: Bug Diagnosis** - Search error → Locate function → Trace dependencies → Find discrepancy → Verify with MCP → Report
- **Tree 2: Architecture Analysis** - Get overview → Identify entry points → Trace dependencies → Build graph → Analyze patterns → Report
- **Tree 3: Performance Analysis** - Search slow operations → Trace data flow → Identify bottlenecks → Measure impact → Verify best practices → Report

Choose based on user's request type. Can combine multiple trees for complex analyses.

---

## Enforcement Rules

**See:** @.claude/skills/analyze-code/references/enforcement-rules.md

**Summary:**

### Rule 1: No Naked Claims
Every claim MUST have file:line reference and evidence from intelligence queries or MCP verification.

### Rule 2: Intel Before Reading
Query project-intel.mjs BEFORE reading any files. Achieve 90-97% token savings.

### Rule 3: MCP for Authority
Verify library/framework behavior with authoritative MCP sources, not memory or assumptions.

**These rules are non-negotiable. Violations invalidate the analysis.**

---

## 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)

---

## Prerequisites

Before using this skill:
- ✅ PROJECT_INDEX.json exists (run `/index` if missing)
- ✅ project-intel.mjs is executable
- ✅ Code to analyze exists in repository
- ⚠️ For external library analysis: MCP tools configured (Ref, Context7)

---

## Dependencies

**Depends On**:
- None (this skill is standalone and doesn't require other skills to run first)

**Integrates With**:
- **debug-issues skill**: Use after this skill if analysis reveals bugs
- **create-implementation-plan skill**: Use after this skill to plan fixes/enhancements

**Tool Dependencies**:
- project-intel.mjs (intelligence queries)
- MCP Ref tool (library documentation)
- MCP Context7 tool (external docs)

---

## Next Steps

After analysis completes, typical next steps:

**If bugs found**:

analyze-code → debug-issues skill → create-implementation-plan skill → implement-and-verify skill

**If performance issues found**:

analyze-code → create-implementation-plan skill (optimization) → implement-and-verify skill

**If architecture review**:

analyze-code → create-implementation-plan skill (refactoring) → implement-and-verify skill

**Commands to invoke**:
- `/bug` - If analysis reveals specific bugs
- `/plan` - To create implementation plan for fixes
- `/implement` - After plan exists, to execute changes

---

## Failure Modes

**See:** @.claude/skills/analyze-code/references/failure-modes.md

**Summary of 5 Common Failures:**

1. **PROJECT_INDEX.json Missing** - Solution: Run `/index`
2. **Intelligence Queries Return No Results** - Solution: Regenerate index, broaden search
3. **MCP Tools Not Available** - Solution: Configure .mcp.json, use workaround
4. **Analysis Scope Too Broad** - Solution: Define narrow scope in analysis-spec.md
5. **CoD^Σ Evidence Missing** - Solution: Save intel results, complete CoD^Σ trace

**Diagnostic Workflow**: Check index → Check queries → Check MCP → Check scope → Check evidence

---

## Related Skills & Commands

**Direct Integration**:
- **debug-issues skill** - Use after this skill when bugs are identified
- **create-implementation-plan skill** - Use after analysis to plan changes
- **/analyze command** - User-facing command that invokes this skill
- **code-analyzer subagent** - Subagent that routes to this skill

**Workflow Context**:
- Position: Can be used at any time (analysis is standalone)
- Triggers: User mentions "analyze", "review", "understand", "architecture"
- Output: report.md or analysis-spec.md using templates

---

## Agent Integration

**Subagent Usage**:

When the code-analyzer subagent delegates work to this skill, it provides:
- Initial problem statement
- Suspected file locations (if known)
- Context from user conversation

This skill then:
1. Creates analysis-spec.md from provided context
2. Executes intelligence queries
3. Generates report with CoD^Σ trace
4. Returns findings to subagent

**Task Tool Example**:
```python
# From code-analyzer subagent
Task(
    subagent_type="code-analyzer",
    description="Analyze infinite render bug",
    prompt="""
    @.claude/skills/analyze-code/SKILL.md

    User reports: LoginForm component re-renders infinitely

    Use intelligence-first approach:
    1. Query project-intel.mjs for LoginForm location
    2. Analyze symbols to find hooks
    3. Verify React patterns with MCP Ref
    4. Generate report with CoD^Σ trace

    Output: Complete report.md with root cause and fix
    """
)

---

Version

Version: 1.1.0 Last Updated: 2025-10-23 Change Log:

• v1.1.0 (2025-10-23): Refactored to progressive disclosure pattern (<500 lines)
• v1.0.0 (2025-10-19): Initial version

Owner: Claude Code Intelligence Toolkit