Dive

Dives deep into your project to investigate any question, from business logic to technical implementation. Uses layered search strategy to find evidence-based answers backed by documentation and code.

Philosophy

Why Dive?

Dive exists because assumptions are dangerous.

The core question isn't "how do I find the answer?" but "how do I know my answer is true?"

The Fundamental Problem:
├── Memory is unreliable (yours and the codebase's docs)
├── Code evolves faster than documentation
├── "I think it works like..." is not evidence
└── Only the current codebase tells the current truth

Evidence Over Intuition

Intuition: "This probably uses X pattern"
Dive:      "render.ts:273 shows reconcileKeyedChildren() implementation"

Intuition is a starting point, not an answer. Dive converts intuition into verified knowledge through evidence gathering.

Layered Search: Why This Order?

Layer 1: Documentation  → What the project CLAIMS to do
Layer 2: Code           → What the project ACTUALLY does
Layer 3: Deep Analysis  → HOW it all connects

Why documentation first?

• It's faster to read
• It gives you vocabulary for code search
• Discrepancies between docs and code are themselves findings

Why code second?

• Code is ground truth—it can't lie about what it does
• Tests show expected behavior in executable form
• Types reveal contracts and constraints

Why deep analysis last?

• It's expensive (time, context)
• Only needed when layers 1-2 don't converge
• Cross-component questions need tracing

Cross-Referencing Reveals Truth

When documentation says X but code does Y:

• The code is always correct about behavior
• The documentation reveals intent or outdated understanding
• The discrepancy itself is valuable information

This is not a failure of search. It's a success—you found something real.

Core Concepts

Evidence Has Hierarchy

Not all evidence is equal:

| Source | Reliability | What it proves | | ---------------- | ----------- | ----------------- | | Running code | Highest | Current behavior | | Tests | High | Expected behavior | | Implementation | High | How it works | | Type definitions | Medium-High | Contracts | | Comments | Medium | Developer intent | | Documentation | Medium | Claimed behavior | | Commit messages | Low-Medium | Historical intent |

Multiple sources agreeing = high confidence. Single source = verify with another layer.

The Question Shapes the Search

Different questions need different approaches:

"How does X work?" → Start with code, verify with tests "Why is X designed this way?" → Start with docs/ADRs, check history "What calls X?" → Start with grep, trace references "When did X change?" → Start with git log, find the commit

Don't apply the same search pattern to every question. Let the question guide you.

Uncertainty is Information

When you can't find clear evidence:

• State what you searched
• State what you found (even partial)
• State what's missing
• Offer hypotheses, clearly labeled as such

"I couldn't find X" is a valid finding. It tells the next investigator where not to look.

The Dive Loop

1. Understand: What exactly is being asked?
      ↓
2. Search: Layer 1 → Layer 2 → Layer 3 (as needed)
      ↓
3. Collect: Gather evidence with file:line citations
      ↓
4. Synthesize: What do the sources tell us together?
      ↓
5. Respond: Direct answer + evidence + uncertainty

This isn't a checklist to follow blindly. It's a mental model for thorough investigation.

When Layers Conflict

Documentation says one thing, code does another. This is common. Here's how to think about it:

| Situation | What to trust | What to report | | --------------- | ------------- | -------------------------- | | Docs outdated | Code | Note the discrepancy | | Feature removed | Code | Flag potential doc cleanup | | Docs wrong | Code | Recommend doc fix | | Code buggy | Neither | Flag as potential bug |

The key: always report both, let context determine action.

Reference

Load these as needed, not upfront:

• reference/search-strategies.md - Detailed search patterns
• reference/code-search-patterns.md - Code navigation techniques
• reference/evidence-collection.md - Citation formats and templates

Understanding, Not Rules

Instead of memorizing anti-patterns, understand the underlying tensions:

| Tension | Resolution | | ------------------------- | --------------------------------------------------------------------------------------- | | Speed vs Thoroughness | Match depth to stakes. Quick question? Layer 1 may suffice. Critical decision? Go deep. | | Confidence vs Evidence | Never state confidence without evidence. "I'm 90% sure" means nothing without sources. | | Intuition vs Verification | Use intuition to guide search, not to answer. Then verify. | | Completeness vs Relevance | Answer the question asked. Note related findings briefly, don't digress. |

The goal isn't to follow a procedure. It's to know when you know something is true.