deep-code-intelligence

Deep Code Intelligence

Use this skill when the task is too important, ambiguous, or coupled for a fast “implement first” approach.

Goal

Increase solution quality by forcing Claude to gather evidence, expose hidden assumptions, and compare multiple paths before changing code.

Core loop

1. Build a repo fingerprint

Collect only the facts that change the decision:

• key modules and ownership boundaries
• hot paths and integration seams
• build/test entrypoints
• persistence and migration surfaces
• feature flags / config gates

2. Extract constraints

Split into:

• explicit constraints — user asks, tests, types, configs, docs
• implicit constraints — backward compatibility, ordering, idempotency, auth, observability, performance envelopes

3. Create a hypothesis ladder

Do not settle on one explanation early. Generate:

• most likely explanation,
• strongest competing explanation,
• weird but costly explanation.

Prefer the next step that invalidates bad theories quickly.

4. Build an evidence matrix

Use a compact table:

Topic	Evidence	Confidence	Next check
Cause of failure	stack trace + source path + failing test	0.78	reproduce with logging

If confidence is low, say so plainly.

5. Compare options

Every serious recommendation should beat at least one credible alternative. Score options on:

• correctness
• complexity
• blast radius
• reversibility
• validation speed
• long-term maintainability

6. Stage validation

Front-load cheap validation:

1. static checks / grep / type clues
2. unit or focused tests
3. integration checks
4. runtime observation
5. broad regression sweep

7. Capture residual risk

End with what is still unknown and what would change the recommendation.

Heuristics

• Prefer narrow fixes when system understanding is weak.
• Prefer structural fixes when the same class of defect is likely to recur.
• Prefer observability improvements when certainty is low.
• Prefer reversible migrations over one-shot transformations.
• Prefer behavior-oriented tests over implementation snapshots.

Escalation guide

Situation	Escalate to	Why
Need repo-wide synthesis	principal-engineer-strategist	Better architectural judgement and option scoring.
Need multi-track execution	team-orchestrator	Handles parallel work and audit loops.
Need library or framework truth	research-orchestrator + Context7	Reduces hallucination risk and validates API usage.
Need final pressure-test	audit-reviewer or /cc-council	Catches blind spots before delivery.

Minimal output standard

A good response should include:

• problem frame,
• evidence summary,
• constraints,
• at least 2 options,
• recommendation,
• validation plan,
• residual risk.