Research

Persistent project-scoped store for deep research findings. You activated this skill because the user asked a substantive research question, or invoked it explicitly with /research <topic>.

If invoked with a topic argument (e.g. /research tailwind-v5), use it as the seed for Retrieval - start by looking up that topic in INDEX.md. Don't research blindly; the lookup may answer immediately.

When to use

• "what's the latest npm package that does X"
• "compare A vs B vs C for 2026"
• "which engines / frameworks / libraries can clone X fast"
• "research how Y works under the hood"
• "deep dive on Z"
• User pastes a long markdown research dump and asks you to save it

When NOT to use

• Plan-stage notes
• Small facts or one-line preferences
• Code-level decisions tied to one file
• Casual lookups answerable from a single source with no synthesis
• Recording personal ideas or musings
• As a substitute for a single WebSearch or WebFetch

If a single WebSearch + 1-2 sentences answers the question, you don't need this skill.

Setup (first use only)

On first activation in a project, do this once:

1. Resolve project root: git rev-parse --show-toplevel 2>/dev/null || pwd

2. Create <root>/.research/ if missing

3. Create <root>/.research/INDEX.md with this exact content:

   # Research index
   
   | Topic | Path | Last verified | One-liner |
   |---|---|---|---|
   

4. Add .research/ to <root>/.gitignore. If .gitignore doesn't exist, create it. Research data may contain proprietary insights, default private.

The data lives at <root>/.research/ (sibling of .claude/, not nested inside it). It is a top-level project directory chosen so research data is colocated with the project, gitignored by default, and easy to find by name. Auditing remains intact: every read and write goes through the host's normal permission system.

Workflow

1. Retrieval (the read side - this is how the skill saves your context)

The whole point of this system is progressive disclosure: don't load what you don't need. INDEX.md is your dispatcher - it lets you decide which entries to load without paying to load them. Walk the hierarchy from cheapest to most expensive; only escalate when the previous tier doesn't answer the question.

Loading hierarchy (cheapest → most expensive)

Lookup procedure

1. Read INDEX.md first (tier 1). Scan the one-liner summary column against the user's question. This is the dispatcher - same role as RESOLVER.md in GBrain.

2. Match decision:

   • Strong match - one entry's one-liner clearly covers the topic → go to step 3 with that entry.
   • Multiple plausible matches - load ## Summary of each (still cheap at tier 2). Pick the one(s) that actually answer.
   • Weak / no match → fall through to Investigation. A new entry will be added.

3. Read only the matched entry's ## Summary (tier 2):

   sed -n '/^## Summary/,/^## /p' <root>/.research/<slug>/FINDINGS.md
   

   Usually enough.

4. Escalate one tier only when needed:

   • Question needs claims-level detail beyond the Summary → load the full FINDINGS.md body (tier 3).
   • Question is "have we tried X before / what was discarded?" → sed just that section: sed -n '/^## Discarded approaches/,/^## /p' <root>/.research/<slug>/FINDINGS.md. Don't load the rest.
   • Question references a paste-cited claim → open that specific file under raw/ (tier 4).
   • Question spans topics covered by separate entries → follow related:, repeat tiers 2-3 on each.

5. Fall through to Investigation. Pick the mode:

   • No entry exists in INDEX.md → Investigation in new entry mode.
   • Existing entry doesn't actually resolve the question (problem still unsolved) → Investigation in merge mode (pass existing entry content to the subagent).
   • Existing entry is stale on a fast-moving topic → Investigation in merge mode (refresh, don't quote).

What NEVER to do

• Don't load everything. The schema exists so you can be selective.
• Don't load the full body when Summary suffices. If 3 lines answer it, don't pull 300.
• Don't load raw documents speculatively. They're heavy; most questions don't need them.
• Don't re-read an entry you already loaded this session - unless it was updated since.

INDEX.md as dispatcher

INDEX.md exists only so you can decide which entries to load without loading them. The one-liner column is the entire signal you have before paying for an entry read - write it specifically when storing.

Keep INDEX.md tight: under ~100 rows. If it grows beyond that, prune or archive. The whole token-saving design collapses if INDEX.md itself becomes a bloat source.

2. Investigation (when fresh research is needed)

Spawn a general-purpose subagent with model: "opus" and run_in_background: true. The Investigation phase needs a strong model: the contrarian pass and synthesis steps depend on reasoning depth that smaller models won't deliver. Background mode keeps the conversation interactive: the user can keep working while research runs. Storage runs asynchronously when the agent's completion notification arrives.

The subagent does research and returns its synthesis as structured text. It does NOT write any files. You (main agent) handle all file writes in Storage. This split keeps responsibility clean: the subagent has zero context and doesn't need to know your schema or INDEX.md layout.

Naming convention. Set the Agent tool's description parameter to Research investigation: <topic> (3 to 5 words). This makes research-skill spawns identifiable in the harness UI.

On completion notification: parse the agent's return, apply Storage immediately, surface a brief notice to the user (e.g. "research on <topic> saved to <path>"). Do not dump the full findings into chat unless asked.

Subagents have zero prior context. They don't see this skill, CLAUDE.md, or our conversation. Brief them completely. There is no continuation in this harness - the SendMessage tool to resume an agent is not available. One-shot only. If gaps remain, re-spawn with a refined brief.

The mode (new entry vs merge) was decided in Retrieval phase 5. Brief the subagent accordingly:

• New entry mode - standard brief, no existing context to feed.
• Merge mode - paste the existing entry's ## Summary and any relevant ## Findings sections into the brief, marked clearly as "current state of the entry - verify, update, or supersede". Tell the subagent to flag claims that are now wrong.

Brief checklist

Every Investigation brief MUST include:

• "You have zero prior context" preamble
• Today's actual date (run date +%Y-%m-%d first; pass the literal string)
• Year-pinning rule for WebSearch queries (don't trust the subagent's model prior on what year it is)
• At least 2 independent sources per non-trivial claim. Sources are gathered into a single ## Sources block at the end of the return; do NOT cite inline.
• The cognitive phases below as explicit numbered steps
• The subagent's required output format (below)
• The strict no-[n] / no-inline-URL rule for the Findings body (see Required output format)
• Merge mode only: the existing entry content the subagent should verify / supersede

Cognitive phases (include verbatim in the subagent brief)

The subagent walks the