Analyze

Analyze Skill

When this skill activates, IMMEDIATELY invoke the script. The script IS the workflow. Do NOT explore the codebase first.

Triggers

• analyze this codebase - architecture and quality focus
• review code quality - quality focus
• run security assessment - security focus
• architecture review of this system - architecture focus
• find code smells - quality focus

Quick Reference

Security

When using the Bash tool, all arguments containing variable or user-provided input MUST be quoted to prevent command injection vulnerabilities. Refer to the repository style guide on Command Injection Prevention (CWE-78).

WRONG: grep $PATTERN /some/path CORRECT: grep -- "$PATTERN" /some/path

When to Use

Use this skill when:

• Investigation spans multiple files or components
• Analysis requires structured multi-step exploration
• Findings need prioritization by severity with file:line evidence

Use direct code reading instead when:

• Checking a single file or function
• The question has a known, specific location
• A quick grep or symbol search answers the question

References

• Working with Legacy Code - Bottom-up refactoring through the Software Hierarchy of Needs
• OODA Loop - Decision-making framework mapped to analyze phases
• Tell, Don't Ask - Detect feature envy and getter chain code smells
• Boy Scout Rule - Scope improvement recommendations by size
• Observability Pillars - Logs, metrics, traces for investigation methodology
• Engineering Complexity Tiers - Classify components by tier, evaluate pattern appropriateness
• Agent Architecture Patterns - Skill budget rule, structured prompt design, diagnostic signals for agent reliability
• Context Budget Management - Context flood prevention, Think in Code principle, hook architecture for session continuity

Scripts

Invocation

python3 scripts/analyze.py \
  --step-number 1 \
  --total-steps 6 \
  --thoughts "Starting analysis. User request: <describe what user asked to analyze>"

Process

The script outputs REQUIRED ACTIONS at each step. Follow them exactly.

Phase 1: Exploration (Step 1)

Delegate to Explore agent(s). The script determines scope and parallelism. Wait for all agents, then re-invoke scripts/analyze.py with --step-number 1, including the Explore results in --thoughts.

Phase 2: Focus Selection (Step 2)

Classify investigation areas by dimension (architecture, performance, security, quality). Assign priorities P1-P3. Estimate total steps.

Phase 3: Investigation Planning (Step 3)

Commit to specific files, questions, and hypotheses per focus area. This creates a contract verified in the verification phase.

Phase 4: Deep Analysis (Steps 4 to N-2)

Execute the investigation plan. Read files, collect evidence with file:line references and quoted code. Trace root causes across files.

When analysis discovers book-depth conditions, invoke software-engineering-library and open the matching reference before recommending the fix. Conditions include low test coverage, old file age, hard-to-test seams, external API calls, queues, retries, transaction boundaries, event ordering, schema evolution, layer dependency direction, bounded context splits, and module interface shape. This keeps the heavy guidance deferred until evidence shows it matters.

Phase 5: Verification (Step N-1)

Audit completeness against step 3 commitments. Identify gaps. If gaps exist, increase total-steps and return to deep analysis.

Phase 6: Synthesis (Step N)

Consolidate verified findings by severity (critical, high, medium, low). Identify systemic patterns. Produce prioritized action plan.

Example Sequence

# Step 1: Start, script instructs you to explore first
python3 scripts/analyze.py --step-number 1 --total-steps 6 \
  --thoughts "Starting analysis of auth system"

# [Follow REQUIRED ACTIONS: delegate to Explore agent, wait for results]

# Step 1 again with explore results
python3 scripts/analyze.py --step-number 1 --total-steps 6 \
  --thoughts "Explore found: Flask app, SQLAlchemy, auth/ dir..."

# Step 2+: Continue following script output
python3 scripts/analyze.py --step-number 2 --total-steps 7 \
  --thoughts "[accumulated state from step 1] Focus: security P1, quality P2"

Anti-Patterns

Verification

After execution:

• All priority areas investigated with file-level evidence
• Findings include severity classification (critical/high/medium/low)
• Each finding has specific file:line references
• Synthesis step completed with prioritized recommendations
• No investigation areas left unexplored from the plan