markus41/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.