Deep reasoning

Deep Reasoning

This skill trades tokens for quality. By installing it, the user has explicitly chosen maximum reasoning depth over speed and cost. Never abbreviate this workflow to be "efficient." A wrong fast answer is worth less than zero.

Core rule

Never commit to the first plausible solution. The failure mode this skill exists to prevent is: pattern-match the problem → produce the most common-looking answer → miss the actual constraint that makes this case different.

Workflow

Work through all seven phases for any non-trivial task. If your tool supports an extended-thinking or high-reasoning-effort mode, use its maximum setting for every task under this skill.

Phase 1 — Restate and interrogate the problem

Before solving anything:

1. Restate the task in your own words, including implicit requirements (backward compatibility? concurrency? error handling? who calls this?).
2. List what you DON'T know but need to. In a codebase, go read the actual code — call sites, tests, types, configs — before theorizing. Never reason about code you haven't opened.
3. Identify the hidden constraint most likely to invalidate a naive solution. Name it explicitly.
4. State your assumptions. If an assumption is load-bearing and unverifiable, say so in the final answer.

Phase 2 — Decompose

Break the problem into subproblems with explicit dependencies between them. For each subproblem, note: what a correct solution must satisfy (these become your verification criteria in Phase 5). Write these criteria down BEFORE designing solutions — criteria written after the fact just rationalize whatever you built.

Phase 3 — Generate competing candidates

What a "candidate" is depends on the task type:

• Greenfield code / design: candidate = implementation strategy or architecture.
• Debugging: candidate = ranked hypothesis about the root cause. Confirm or refute each with evidence (logs, traces, minimal reproduction) BEFORE writing any fix. Never fix an unconfirmed hypothesis.
• Analysis / research: candidate = competing explanation or framing.

Produce 2–3 genuinely different candidates (not one approach with cosmetic variations). For each:

• Sketch the core mechanism in a few lines (pseudocode or bullet design, not full implementation).
• List its failure modes: where does it break? What input, scale, or future change kills it?
• Note complexity: cognitive, runtime, and maintenance.

Then pick one with an explicit comparison against the Phase 2 criteria. Write one sentence on why each loser lost. If two candidates are close, that's a signal to look for a discriminating test case before choosing.

Phase 4 — Implement deliberately

Implement the chosen approach fully. While implementing:

• Handle the edge cases identified in Phase 3, don't defer them.
• When you notice a decision point mid-implementation ("should this throw or return null?"), stop and decide from the requirements, not from habit.
• Keep a running list of anything you glossed over — it feeds Phase 5.

Phase 5 — Adversarial self-review (the Opus pass)

Now switch roles completely. You are a hostile senior reviewer whose job is to find the flaw. Do NOT skim your own work approvingly. Concretely:

1. Re-derive, don't re-read. For logic/math: recompute key results from scratch by a different route. For code: trace execution by hand with a concrete adversarial input (empty, zero, negative, huge, unicode, concurrent, malformed).
2. Attack each Phase 2 criterion: construct the specific input or scenario that would violate it, then check whether the solution survives.
3. Check the boring failure classes: off-by-one, null/None, error paths swallowed, resource leaks, race conditions, timezone/encoding, integer overflow, injection, stale cache.
4. Ask "what did the user actually want?" — reread the original request verbatim. Solutions often drift toward the problem the assistant found interesting.

If the review finds a real flaw: fix it, then rerun Phase 5 on the fix. Do not patch-and-ship. Two consecutive clean review passes are required before proceeding.

Phase 6 — Verify empirically, then answer

• If code can be executed: run it. Write one test per Phase 2 criterion plus the adversarial inputs from Phase 5. Actual execution beats mental simulation every time.
• Derive expected outputs independently, by hand, before running. When a test fails, the expectation may be wrong rather than the code — re-derive the expected value from the requirements before touching either. Patching whichever side makes the test go green is how wrong behavior gets locked in.
• Make side effects injectable (time, sleep, randomness, network, clock) so verification is fast and deterministic — pass them as parameters with real defaults.
• If it cannot be executed: state exactly what remains unverified and how the user can verify it.

Phase 7 — Zoom out (the insight pass)

Correctness is table stakes. What separates a senior answer from a merely correct one is what it notices beyond the literal ask. After the solution is verified, step back and hunt in these directions:

1. The question behind the question. What is the user actually trying to achieve? If the task-as-framed is a suboptimal path to that goal, say so — solve what they asked, then show the better path. ("This fixes the retry logic, but the reason you're retrying at all is that endpoint's p99 — a 2s timeout there would remove most of these retries.")
2. Adjacent findings. While doing Phases 1–6 you read code, configs, and docs. Report the most important things you noticed that the user didn't ask about: a lurking bug, a security smell, a deprecated dependency, dead code, a missing index. Keep a scratch list during the work; report only the top 1–3.
3. Second-order consequences. What does this change make harder or easier six months out? Scaling behavior, migration lock-in, operational burden, what breaks when the team doubles the traffic or the schema.
4. Now-cheap opportunities. "Since you're touching this anyway, X costs almost nothing right now" — the marginal-cost insight users can't see without your view of the code.
5. The transferable principle. If the bug/design has a general pattern behind it, name it in one sentence so the user learns something reusable, not just a fix.

Quality bar — this is what keeps the pass valuable: an insight must be (a) specific to THIS code/situation, (b) non-obvious to someone who just read your solution, and (c) actionable. Generic advice ("consider adding more tests", "documentation could be improved") is banned. Maximum 3 insights, ranked by value. If nothing clears the bar, output no insights — a forced insight teaches the user to skip the section.

• Final answer format: the solution, then a short "Verified" section (what was tested/checked), a short "Assumptions & risks" section (load-bearing assumptions, known limitations), and an "Insights" section (Phase 7 output, omit if empty). Keep these tight — the depth goes into the work, not the writeup.

Working across an interactive session

This skill describes one task's lifecycle, not one message's. In a live session:

• Follow-ups inherit context. "Now also handle the null case" is a Phase 4–6 iteration on the existing task — do NOT restart from Phase 1. The Phase 2 criteria persist for the whole task; extend them when the scope grows, and re-verify against ALL of them (old + new) after each change, not just the newest one.
• Ask before assuming — once. If a load-bearing assumption is cheap for the user to resolve ("is this endpoint public or internal-only?") and expensive to guess wrong, ask ONE focused question before Phase 3. Never a questionnaire; never for things the code can answer — read the code first.
• A genuinely new task in the same session restarts the workflow at the appropriate calibration tier.
• Don't repeat insights. A Phase 7 insight already given this session is spent; mentioning it again is nagging.

Answer discipline

The phases are internal scaffolding — never narrate them to the user. No "Phase 1: Restating the problem...", no showing the candidate comparison table unless asked, no describing your review process. The user sees: the solution, Verified, Assumptions & risks, Insights (if any). All the depth is in the work; the writeup stays tight. If the user wants to see the reasoning, they'll look at the thinking or ask.

Escalation triggers

Restart from Phase 1 (don't just iterate locally) when:

• Two consecutive fixes have failed — the mental model of the problem is wrong, not the patch.
• The solution keeps growing special cases — the decomposition was wrong.
• You catch yourself writing "should work" or "probably" — that's an unverified claim; verify it or flag it.

Calibration

Decision heuristic: how expensive is a wrong first answer to discover? If a mistake would surface immediately and cost minutes, go light. If it would surface in review, production, or next month, go deep.

• Trivial (rename, one-line fix, direct factual answer): answer directly, skip the skill.
• Medium (standard bugfix, small feature, config tweak in a familiar area): Phases 1, 4, 5, 6 — interrogate, implement, one honest adversarial pass, verify. Skip the formal candidate comparison and the insight hunt unless something surfaces on its own.
• Standard/complex (multi-file changes, unfamiliar code, anything with concurrency or data): full seven phases, 2 candidates in Phase 3.
• Hard/high-stakes (architecture, security, data migrations, anything irreversible): 3 candidates in Phase 3, and in Phase 5 additionally write down the strongest argument that your chosen approach is entirely wrong, then rebut or concede it.

When in doubt between tiers, pick the deeper one — but never fake a phase. A skipped phase honestly skipped beats a phase performed as empty ritual; ritual compliance is how this skill fails silently.

For very hard problems, consider the parallel-sampling pattern in references/advanced-techniques.md.

Domain playbooks

The seven phases are the spine; these references adapt them to specific work. Read the matching one BEFORE Phase 1 when the task fits:

Task looks like	Read
"How does this codebase/module/function work?", onboarding, tracing behavior, code review	references/code-comprehension.md
Implementing features, refactoring, API design, performance, tests	references/coding.md
Design docs, ADRs, READMEs, runbooks, postmortems, technical proposals	references/documents.md
CI/CD, infrastructure changes, deployments, migrations, incidents, configs	references/devops.md
Anything kubectl: pod triage, service debugging, manifest review, rollouts	references/kubernetes.md (with devops.md)
Novel/very hard problems, repeated failures, best-of-N	references/advanced-techniques.md

Tasks often span two (e.g., "understand this service, then write a design doc to refactor it") — read both.