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

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):
   bash project-intel.mjs --overview --json > /tmp/analysis_overview.json
   Purpose: Understand project structure, entry points, file counts
   Tokens: ~50

2. Search for Relevant Files:
   bash 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):
   bash 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:
   ```bash
   # 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 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 <pattern>")
↳ Source: project-intel.mjs --search "<pattern>" --type <type>
↳ Data: [What was found]
↳ Tokens: [Token count]

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

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

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

Step 5: ∘ Conclusion
↳ Logic: [Reasoning from data to conclusion]
↳ Root Cause: <file>:<line> - [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

```