cofin/deepthink

Deepthink

Structured extended reasoning with hypothesis tracking and confidence progression. Prevents circular thinking by explicitly tracking what's been explored, what evidence exists, and what confidence level has been reached.

References perspectives for multi-angle evaluation when confidence is stuck and a fresh frame is needed.

<workflow>

Workflow

1. Frame the Problem

State what you're trying to understand or decide, specifically. Vague framing produces vague investigation.

2. Form Initial Hypothesis

Your best guess based on available information. One sentence. Confidence: exploring.

Don't skip this step — even a weak hypothesis focuses investigation better than no hypothesis.

3. Gather Evidence

Read code, check docs, run tests, trace execution. Record what you find at each step. Every piece of evidence should be evaluated against the current hypothesis.

Note: Sequential-thinking or similar extended reasoning tools can complement complex sub-steps within this workflow — particularly during evidence gathering (step 3) or when evaluating a hypothesis with many interdependencies. Use them to decompose a stuck sub-step without abandoning the overall hypothesis tracking structure.

4. Evaluate Against Hypothesis

Does the evidence support, contradict, or require revision?

• Supports: confirms a specific aspect of the hypothesis
• Contradicts: rules out a specific aspect, requiring revision
• Requires revision: the hypothesis was wrong in some way — update it now

5. Update Confidence

Based on evidence quality and coverage, update the confidence level:

| Level | Meaning | Action | | ----- | ------- | ------ | | exploring | Just started, no hypothesis yet | Gather initial evidence, form hypothesis | | low | Have a hypothesis but weak evidence | Seek confirming/disconfirming evidence | | medium | Evidence supports hypothesis but gaps remain | Fill specific gaps, check edge cases | | high | Strong evidence, minor uncertainties | Verify the uncertainties aren't critical | | certain | Conclusive evidence, ready to act | Synthesize findings and present |

Escalation rule: If confidence has not increased after 3 investigation steps, stop and reassess. Either the hypothesis is too broad, you're looking in the wrong place, or you need a different tool (flow:tracer, flow:perspectives).

6. Decide: Continue or Conclude

• Continue: identify exactly what's missing and loop back to step 3 with a specific target
• Conclude: if confidence is high or certain, synthesize findings and present

Investigation is complete when: confidence is high/certain, all evidence-against items are explained, the hypothesis is a specific actionable conclusion, and unexplored areas are evaluated or ruled out as non-critical.

</workflow> <guardrails>

Guardrails

• Evidence hoarding — Reading files without updating hypothesis. Every read should confirm, contradict, or refine your current hypothesis. If it doesn't, you're reading the wrong thing.
• Premature conclusion — Presenting hypothesis as conclusion before gathering evidence. A hypothesis is not a conclusion. Don't present it as one.
• Permanent exploring — Staying at exploring after 5+ checks without narrowing. Formulate a hypothesis and commit to testing it.
• Circular investigation — Revisiting same evidence without new framing. If you're back where you started, the hypothesis needs to change, not the evidence gathering.

</guardrails> <validation>

Validation Checkpoint

Before presenting the conclusion, verify:

• [ ] Hypothesis was updated at least once during investigation
• [ ] Evidence for AND against was recorded
• [ ] Confidence level progression is justified by evidence
• [ ] Investigation concluded with a specific, actionable finding

</validation> <example>

Example

Debugging: "Tests pass locally but fail in CI."

• Hypothesis 1: "Flaky test — timing issue" (confidence: exploring)
• Evidence: CI logs show deterministic failure on same test. Rules out flakiness. → Revise.
• Hypothesis 2: "Environment difference — missing env var" (confidence: low)
• Evidence: Compared CI env vs local. Found DATABASE_URL uses different host. Test creates real DB connection. → confidence: medium.
• Hypothesis 3: "CI database not seeded" (confidence: medium)
• Evidence: CI setup script skips seed step for test DB. Local has leftover seed data. → confidence: high.
• Conclusion: CI test DB is empty. Fix: add seed step to CI pipeline before tests.

</example>

Complements

• systematic-debugging — deepthink provides structured hypothesis evolution when debugging stalls after 3+ iterations
• brainstorming — deepthink enables deeper analysis during the design phase when approaches need thorough evaluation
• flow-plan — deepthink supports thorough requirement analysis for complex decomposition decisions

References Index

• Reasoning Strategy — When to use deepthink, the 6-step workflow, and anti-patterns to avoid
• Confidence Tracking — Confidence levels table, what to track at each step, escalation rule, and completion criteria