deep-research

Deep Research

Become an expert on a topic before producing any output. Research first, report second, then ask conceptual questions before acting.

Inputs

The user provides one or both of:

• A topic (what to become expert on)
• One or more @folder mentions: primary docs/specs, and optionally secondary code folders for validation

If the user gives only a topic, ask which folders are the source of truth before reading anything.

Workflow

Step 1 — Triage, then load primary sources

Start with a lightweight pass before full reads:

1. List all files in the primary folder(s).
2. Read first: README, ARCHITECTURE.md, AGENTS.md, index files, and any doc the user pointed at explicitly.
3. Identify entry points, public exports, and the docs that define the system's vocabulary.
4. Skip or deprioritize: generated code, vendored deps, build output, and snapshot fixtures unless the user asked about them.

Then read remaining primary files end-to-end. Don't grep or sample for files you've committed to reading.

If the folder is large (> 30 files or > 100k tokens estimated), tell the user and ask whether to:

• Read all of it (slower, more accurate)
• Read a triaged subset (you propose the list after Step 1 triage, user confirms)

Step 2 — Validate against secondary sources

If the user provided code folders for validation, cross-check claims in the docs against the actual implementation. Surface any discrepancies you find — outdated docs are common and worth flagging.

Step 3 — Produce a structured report

Use this exact template:

# [Topic] — architecture report

## What it is
[1-2 sentences. The elevator pitch in your own words.]

## The pieces
- **[Component A]** — what it does, where it lives (`path/to/it`)
- **[Component B]** — ...

## How they fit together
[Walk the happy path. Use a flow:
  Input → Component A (does X) → Component B (does Y) → Output]

## Key concepts and terminology
- **[Term]**: [precise definition as used in this codebase, not the generic one]
- ...

## What I'm unsure about
[Numbered list of conceptual questions where the docs were ambiguous or
contradicted the code. Each question is specific and answerable.]

## What looks outdated
[Specific doc paragraphs or code comments that don't match current behavior.
Include file:line references.]