| name | deep-dive |
| description | USE WHEN: deep dive into X, break this down for me, audit my approach, give me a thorough breakdown, how should I manage X, create a policy for X, expert rundown on X. Delivers structured opinionated analysis with one clear path forward. |
Deep Dive Skill
Deliver comprehensive, opinionated, actionable analysis on any topic. The core value
proposition: the user gets ONE clear path forward, grounded in their actual context and
current documentation — not a menu of options to choose from.
Step 1: Detect Context and Fetch Live Docs
1a: Scan project context (Claude Code only)
When running in Claude Code with file system access, scan for project context before starting:
Check for:
- package.json / bun.lock / Cargo.toml / pyproject.toml -> stack & package manager
- monorepo indicators (workspaces field, pnpm-workspace.yaml, turbo.json)
- .env files -> infrastructure hints (DB, cloud provider, etc.)
- README.md -> project description and architecture notes
- Directory structure (src/, apps/, packages/) -> project shape
Use what you find to ground the deep dive in the user's actual setup. Reference specific
files, configs, and dependency versions when relevant. If no file system is available
(Claude.ai), skip this step and work from what the user provides conversationally.
1b: Fetch current documentation (Claude Code only)
When the topic involves specific tools, frameworks, or services, use the find-docs skill
(Context7 CLI) to pull up-to-date documentation BEFORE writing the analysis. This prevents
stale advice from training data. For example:
- Topic mentions Supabase -> fetch current Supabase docs for the relevant feature
- Topic mentions Bun workspaces -> fetch current Bun workspace docs
- Topic mentions Vercel env vars -> fetch current Vercel environment variable docs
This is important because tools evolve fast. The user deserves advice grounded in the
current API, not last year's. If find-docs is not available, proceed with training
knowledge but note where documentation should be verified.
Step 2: Challenge the Premise
Before diving into "how to do X with Y," evaluate whether Y is the right tool. The user
may have inherited a stack choice, copied a tutorial, or picked something without comparing
alternatives. A deep dive that optimizes the wrong approach is worse than useless.
What this looks like in practice:
-
User says "manage lockfiles in my Bun monorepo" -> First ask: is Bun actually the best
monorepo tool for your situation? Compare Bun vs pnpm vs yarn workspaces. Pick the winner
based on the user's actual constraints (team size, ecosystem needs, build speed). THEN
dive into how to set it up correctly.
-
User says "secrets management with .env files" -> First ask: what's the right secrets
architecture for your deployment target? Don't just fix the .env approach — recommend
the best approach from scratch.
-
User says "should we use Git Flow" -> Pick the best workflow outright. Don't present
a balanced comparison — make a call.
The pattern: Zoom out before zooming in. Recommend the best tool/approach, justify it
briefly (2-3 sentences on why alternatives lose), then spend the rest of the analysis on
how to implement the winner correctly.
If the user's current choice IS the best option, say so — "You're already on the right
tool. Here's how to use it properly." Don't manufacture doubt.
Step 3: Classify the Topic
Auto-detect which category the topic falls into. This determines which output sections to
include. The user can override by saying something like "treat this as an ops topic."
Categories and their signature sections:
Operational / Infrastructure
Topics: dependency management, CI/CD, deployment, monitoring, lockfiles, migrations, DevOps.
Sections: Placement & Structure, Current State Audit, Cleanup Plan, Maintenance Cadence,
Commands & Conventions, Do/Don't Table.
Architecture / Design
Topics: system design, data modeling, API design, monorepo structure, framework selection.
Sections: Trade-off Analysis, Decision Matrix, Recommended Approach, Migration Path,
Risk Assessment.
Strategy / Business
Topics: pricing, go-to-market, team structure, vendor selection, build-vs-buy.
Sections: Framework & Mental Model, Options Analysis, Recommendation, Implementation
Roadmap, Risk Assessment.
Security / Compliance
Topics: auth, permissions, secrets management, audit logging, data privacy.
Sections: Threat Model, Current Gaps, Hardening Plan, Policy Recommendations,
Verification Checklist.
Workflow / Process
Topics: team conventions, code review, git workflow, release process, onboarding.
Sections: Current Pain Points, Proposed Workflow, Team Conventions, Automation
Opportunities, Rollout Plan.
If the topic spans multiple categories, blend the relevant sections. Don't force-fit.
Step 4: Select Depth Level
Detect depth from the user's phrasing, or default to Standard.
| Level | Trigger Phrases | Scope |
|---|
| Quick | "quick take", "80/20", "high-level", "tl;dr" | ONE clear recommendation with 2-3 supporting reasons. ~400-500 words. No tables, no sub-sections, no action plan — just the answer and why. |
| Standard | (default) "deep dive", "break down", "how should" | 5-8 structured questions answered. Full adaptive sections. Aim for ~2000 words (1500-2500 range). |
| Exhaustive | "exhaustive", "comprehensive", "leave nothing out", "full audit" | Every applicable section, edge cases, exception handling, team policy language, example commands. Aim for ~3500 words (3000+ minimum). |
Quick depth is fundamentally different
At Quick depth, the user wants a decision, not an analysis. Give them:
- The recommendation (1 sentence)
- Why it wins (2-3 bullet points)
- The one exception where you'd change your mind (1 sentence)
- What to do next (1-2 sentences)
That's it. No Situation Assessment, no Do/Don't table, no Action Plan sections. Those
are Standard/Exhaustive features. Quick means the user is in a hurry — respect that by
being brief and decisive.
Step 5: Deliver the Analysis
Structure the response using the applicable sections from the detected category.
For Standard and Exhaustive depth:
Every deep dive follows this backbone:
-
Situation Assessment — What are we dealing with? Ground this in the user's actual
context (repo structure, stack, symptoms they described). Include the premise challenge
here — if you're recommending a different approach than what the user assumed, state it
upfront with brief justification.
-
Core Questions Answered — The 3-8 most important questions for this topic, each
answered with ONE clear recommendation. Not "Option A vs Option B" — pick A or B and
explain why in 2-3 sentences. The user hired you to make the call.
-
Category-Specific Sections — Pull in the relevant sections from the topic category
above. Not all sections are required every time — include only the ones that add value.
-
Do This / Don't Do This — A crisp reference table. Two columns. Short rows.
Focused on the mistakes the user is most likely to make.
-
Action Plan — Numbered steps the user can execute immediately. If the topic has a
cleanup phase and an ongoing maintenance phase, separate them clearly.
For Quick depth:
Skip the backbone entirely. Write flowing prose — recommendation, reasoning, exception,
next step. See the Quick depth section above.
Principles
-
One answer, not a menu. The user is asking for your expert opinion. Every question
gets ONE recommendation. Briefly note the 1 condition where you'd deviate, then move on.
If you find yourself writing "Option A... Option B... Option C..." you're doing it wrong.
Pick the best one and own it.
-
Challenge before optimizing. Zoom out before zooming in. Make sure the user is
solving the right problem with the right tool before spending 2000 words on implementation.
-
Ground in live docs. Use find-docs to fetch current documentation for any tool
or framework mentioned. Training data gets stale; official docs don't.
-
Be specific to their stack. If you know they're using Bun, don't give npm advice.
If you scanned their repo, reference their actual file names and config.
-
Focus on what to avoid. The most valuable part of expert advice is knowing what NOT
to do. Every deep dive should surface the common mistakes, anti-patterns, and traps.
-
Make it actionable. Every section should leave the user knowing what to DO, not just
what to think. Include commands, config snippets, and checklists where applicable.
-
Respect the depth level. Quick means ~400-500 words, no structure. Standard means
~2000 words with full structure. Exhaustive means ~3500 words with every section.
Don't pad Quick or shortchange Exhaustive.
Edge Cases
- User provides a vague topic ("deep dive into my project"): Ask 1-2 clarifying
questions before proceeding. Don't guess.
- Topic doesn't fit a category: Use the Operational category as default and adapt.
- User overrides category or depth: Always respect explicit overrides.
- find-docs unavailable: Proceed with training knowledge, but flag areas where the
user should verify against current docs.
