# Researching

> Use when you need to understand unfamiliar code, libraries, or problem domains before designing or planning -- produces a compressed research document with file paths, data flows, and gotchas for human verification

- Skill: `jsarif/researching` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jsarif/researching`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jsarif/researching/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: JSarif (https://skillmd.com/u/jsarif)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jsarif/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

```dot
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

<HARD-GATE>
You MUST present the research document to the human and get explicit approval before proceeding to brainstorming, writing-plans, or any implementation. Bad research poisons everything downstream.

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."
</HARD-GATE>

### 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

```markdown
# 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

| Task Complexity | Research Approach |
|---|---|
| Change a button colour | No research needed |
| Small feature, single file | Quick scan, no formal doc |
| Medium feature, multiple files | One research pass, write the doc |
| Complex system, large codebase | Full research with parallel sub-agents |

## 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.