research

Files (1)

• SKILL.md

SKILL.md (first lines)

# research

Multi-source research. Route sources once, spawn in parallel, synthesize in a
sub-agent with mechanical confidence scoring.

## Context Discipline

This skill runs **inline** in the caller's context so its fetcher `Agent()`
calls are first-level and work (Claude Code only permits 1 level of sub-agent
nesting). To keep the caller's context clean despite running inline:

1. **Fetchers write to scratch files, not the chat.** Each fetcher writes its
   findings to a per-run scratch directory under `$TMPDIR` and returns only a
   one-line `done: <path>` or `unavailable: <reason>`.
2. **A single synthesis sub-agent (opus) reads the scratch files.** The raw
   fetcher output is read and discarded inside the synthesis sub-agent; only
   the compact synthesis lands in the caller's context. In `--report` mode
   the same sub-agent also assembles the Sources appendix from the scratch
   files, so the skill itself never needs to read them.
3. **The skill deletes the scratch directory** after synthesis. In `--report`
   mode, the skill writes the sub-agent's report body to the target path and
   still cleans up the scratch dir (the report itself is the durable
   artifact).

Net effect: caller sees ~5 "fetcher done" lines plus one compact synthesis.
No evidence tables, snippets, or URLs bloat the main context.

## What the Skill Emits to the Caller

The skill prints exactly these blocks to the caller's context — nothing else:

1. **Routing decision** block from Phase 2 (small, bounded).
2. **Fetcher status** map from Phase 3 (one line per routed source).
3. **Synthesis block** from Phase 4, emitted verbatim from the synthesis
   sub-agent.
4. A single line "Report saved to `<path>`" if `--report` was set.

Do NOT print: fetcher narration, intermediate debug output, raw scratch-file
contents, or scratch file paths except inside the FETCHER STATUS block
(where `done: <path>` is bounded internal bookkeeping). If something doesn't
fit the four blocks above, it stays silent.

## Phase 0: Argument Parsing and Setup

Parse `$ARGUMENTS` for these flags:

- `--report` or `--report <filepath>` — Save findings as a markdown report.
  Default path: `.claude/research/<slugified-topic>.md` (create dir if needed).

Everything after flag extraction is the **research question**.

Compute the scratch directory for this run:

```bash
RUN_ID="$(date +%Y%m%d-%H%M%S)-<slug>"
RUN_DIR="${TMPDIR:-/tmp}/claude-research-${RUN_ID}"
mkdir -p "$RUN_DIR"
```

`$TMPDIR` is always writable inside sandboxed sessions (ccw worktrees);
`.claude/` may not be. Scratch files are ephemeral — only `--report` output
lands in `.claude/research/`.

Where `<slug>` is a 4-6 word kebab-case of the topic. The `RUN_DIR` value is
passed to every fetcher and to the synthesis sub-agent.

## Phase 1: Classify the Question

Identify:

- **Primary topic** — what are we researching?
- **Question type** — factual lookup? how-to? comparison? pattern search?
- **Complexity** — simple fact, focused question, or deep analysis?
- **Constraints** — version-specific? performance? architecture?

## Phase 2: Route Sources (DECIDE ONCE)

Select sources using the decision tree below. Output an **explicit committed
list** — these are the sources you will spawn in Phase 3. No "maybe," no
"if needed," no re-decision later.

### Decision tree

```
Is it about a specific library API?
  YES → Context7 (+ gh CLI for real-world usage if needed)

Is it a factual lookup, entity, or "what/who/when" question?
  YES → Serper (fast, structured, cheap)

Is it a "how should I..." or best practices question?
  YES → Tavily (synthesized content) + maybe Serper (for People Also Ask breadth)

Is it about patterns in our codebase?
  YES → Codebase Fetcher (+ gh CLI if comparing to industry patterns)

Is it about how open-source projects solve X?
  YES → gh CLI (+ Tavily if needing written analysis/articles about the approach)
```

### When each source wins

| Source | Best for | Cost |
|--------|----------|------|
| **Context7** | Specific library API, config, version migration | Free (1K/mo) |
| **Serper** | Facts, entities, recency, "what/who/when" | ~$0.001/query |
| **Tavily** | How-to, best practices, technical analysis | ~$0.003-0.008/query |
| **Codebase** | Internal patterns and constraints | Free |
| **gh CLI** | Real-world OSS usage patterns | Free |

### Scaling effort to complexity

| Complexity | Sources | Example |
|-----------|---------|---------|
| Simple fact | 1-2 | "What's the latest version of Prisma?" |
| Focused how-to | 2-3 | "How do I set up connection pooling in sqlx?" |
| Comparison | 3-4 | "What are the tradeoffs between Axum and Actix?" |
| Deep research | 4-5 | "How should we architect real-time notifications?" |

From paulnsorensen/dotfiles, MIT.

More from paulnsorensen/dotfiles