Researching

Researching

Overview

Focused exploration that compresses noise into signal. The goal is a research document -- a compressed, verifiable snapshot of what matters -- not a brain dump of everything you read.

Core principle: Exploration fills context with noise. Research compresses that noise into a document that carries forward only what matters. Every file read, every search result, every dead end gets distilled into a concise artifact.

Announce at start: "I'm using the researching skill to explore [topic]."

When to Use

• Unfamiliar codebase or subsystem ("how does X work?")
• New library, API, or technology to evaluate
• Before brainstorming or writing-plans, when you don't yet understand the landscape
• Task touches code you haven't read

Don't use for:

• Code you already understand
• Simple changes (button colour, config tweak)
• Pure feature ideation (that's brainstorming)

Process

digraph researching {
    "Start: topic + direction" [shape=doublecircle];
    "Scope > 2 areas?" [shape=diamond];
    "Dispatch parallel sub-agents" [shape=box];
    "Explore sequentially" [shape=box];
    "Compress into research doc" [shape=box];
    "Present to human for verification" [shape=box];
    "Human approves?" [shape=diamond];
    "Revise doc" [shape=box];
    "Handoff to brainstorming or writing-plans" [shape=doublecircle];

    "Start: topic + direction" -> "Scope > 2 areas?";
    "Scope > 2 areas?" -> "Dispatch parallel sub-agents" [label="yes"];
    "Scope > 2 areas?" -> "Explore sequentially" [label="no"];
    "Dispatch parallel sub-agents" -> "Compress into research doc";
    "Explore sequentially" -> "Compress into research doc";
    "Compress into research doc" -> "Present to human for verification";
    "Present to human for verification" -> "Human approves?";
    "Human approves?" -> "Handoff to brainstorming or writing-plans" [label="yes"];
    "Human approves?" -> "Revise doc" [label="no"];
    "Revise doc" -> "Present to human for verification";
}

1. Get a starting direction

The human gives you a topic, entry point, keyword, or question. Don't explore blindly.

2. Decide: parallel or sequential?

If the research spans 3+ independent areas (e.g. "understand the crawler, the DB, and the web app"), you MUST dispatch parallel sub-agents using the dispatching-parallel-agents pattern. Each sub-agent explores one area and returns a concise summary. You then merge summaries into the research doc.

Why parallel matters: Sequential exploration of 3+ areas fills your context window with noise from earlier areas while you're still exploring later ones. Parallel sub-agents each start with a fresh context, stay in the smart zone, and return only compressed summaries. This is the core insight from harness engineering -- fresh context windows produce better results.

If the scope is narrow (1-2 areas), explore sequentially.

3. Explore, then compress

Read files, search code, trace data flows. But don't paste raw file contents into your research doc. Compress:

• Reference files with line numbers: schema.ts:5-15 not just schema.ts
• Summarise, don't transcribe: "The crawler uses Stagehand for AI-driven extraction (crawl-venue.ts:34-67)" not 30 lines of code
• Document the data flow: What goes in, what comes out, what transforms it
• Note gotchas and dead ends: What you looked at and dismissed, and why

4. Write the research document

Use the template below. Save to docs/research/YYYY-MM-DD-<topic>.md.

5. Present for human verification

End your message with: "Please review this research document -- especially the Gotchas and Open Questions. Let me know if anything looks wrong or missing before we move forward."

6. Handoff

After approval, you MUST explicitly offer the next step:

• If design decisions are needed → "Ready to move to brainstorming to explore approaches?"
• If the path is clear → "Ready to move to writing-plans to create the implementation plan?"

Do not silently move on. The human chooses when to transition.

Research Document Template

# Research: [Topic]

Date: YYYY-MM-DD

## Intent
What we're trying to understand and why. One paragraph.

## Key Files
- `path/to/file.ts:10-45` — what this section does
- `path/to/other.ts:1-20` — what this section does

## Data Flow / Architecture
How the pieces connect. Diagram if helpful.

## Decisions and Constraints
- Why X was chosen over Y
- Hard constraints (API limits, browser compat, etc.)

## Gotchas
- Thing that surprised you or could trip someone up
- Dead end: tried X, didn't work because Y

## Open Questions
- Things the research couldn't answer
- Decisions that need human input

Adapt sections to fit the research. Greenfield research (library evaluation) might replace "Key Files" with "Options Compared." The structure should serve the content, not the other way around.

Scaling Guidance

Common Mistakes

Exploring 3+ areas sequentially instead of in parallel. If you're researching the crawler, the DB, and the web app, dispatch one sub-agent per area. Sequential exploration fills your context with noise from earlier areas. Parallel sub-agents start fresh and return compressed summaries.

Transcribing instead of compressing. Your doc should be shorter than the code you read, not a copy of it. If a section is >20 lines, you're probably transcribing.

Skipping line numbers. schema.ts is useless for verification. schema.ts:5-15 lets the human spot-check your claims.

Exploring without a direction. Always start from a specific question or entry point. Undirected exploration fills context with noise.

Skipping human verification. The research doc is the highest-leverage review point. A bad line of research poisons everything downstream.

Not offering the handoff. After the human approves, explicitly offer brainstorming or writing-plans as the next step. Don't silently continue.