• "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

• 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

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:
   markdown

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

<root>/.research/

.claude/

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):
   bash

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

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

general-purpose

model: "opus"

run_in_background: true

INDEX.md

description

Research investigation: <topic>

<topic>

<path>

SendMessage

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

• "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

1. Decompose - list sub-claims that would resolve the question; identify what evidence settles each.
2. Gather - for each sub-claim, find ≥2 independent sources (year-pinned WebSearch → WebFetch on top results). Quote verbatim. Don't synthesize yet.
3. Validate - re-derive numbers, benchmarks, version claims. Flag anything that fails.
4. Contrarian pass - actively search for "why is this wrong / scam / criticized / deprecated / known-bad". State the strongest objection found. Skipping this is the most common subagent failure mode. Call it out explicitly in the brief.
5. Synthesize - verdict + citations + residual disagreements listed explicitly. No silent picks.

[1]

[2]

Citation rules. Read carefully and follow exactly:

• Do NOT use

  [n]

  numbered citations. No

  [1]

  ,

  [2]

  , or any bracketed numbers in the Findings body.
• Do NOT put URLs in the Findings body.
• Do NOT add inline footnote markers, anchors, or any per-claim citation tags of any kind.
• Write Findings as plain prose paragraphs.
• When a claim's interpretation depends on which source said it, name the source as prose, no brackets ("per the README", "according to littlemight.com", "the HN-simulator commenter argues..."). No URL, no

  [n]

  .
• Put ALL sources in a single

  ## Sources

  block at the END of the return, one bullet per source:

  - url - fetched YYYY-MM-DD

  . The main agent lifts this block to FINDINGS.md frontmatter.
• Source-count discipline is preserved: at least 2 independent sources per non-trivial claim. The discipline lives in source count, not in inline tagging.

undefined

• url - fetched YYYY-MM-DD
• url - fetched YYYY-MM-DD

• claim from existing entry that is now wrong + reason

The subagent does not write any files. You parse this return and apply Storage rules.

• Small gap (one missing fact, one specific angle) → fill it yourself with a focused WebSearch / WebFetch. Cheaper than re-spawn.
• Large gap (whole sections shallow, contrarian pass clearly skipped) → re-spawn with a refined brief that names the specific gap. The previous return is discarded (no file was written yet).

1. Relevance: does the Summary actually answer what was asked? If the agent disambiguated an ambiguous topic (picked one interpretation of several), confirm it matches the user's intent. If wrong, re-spawn with a tighter brief; do not store.
2. Source quality: count primary URLs vs aggregated WebSearch snippets in the

   ## Sources

   block. If most sources are search-result summaries without specific fetched URLs, the entry is weaker than it looks. Either fill primaries yourself with focused WebFetch, or store but flag the weakness explicitly in

   ## Open questions

   .
3. Contrarian pass evidence: "none found" is rare on any non-trivial topic. If you got "none found", be skeptical: either the topic is genuinely uncontroversial (rare), or the subagent skipped phase 4 (common). If skipped, fill in yourself with focused contrarian searches, or re-spawn.
4. Citation cleanup: if the return contains

   [n]

   markers in the Findings body despite the brief's no-

   [n]

   rule, strip them before writing FINDINGS.md. This is a known failure mode (subagents fall back to academic citation habits). Do not push the noise downstream. Same for inline URLs in the Findings body: strip them. Sources belong in frontmatter.

1. Create

   <root>/.research/<topic-slug>/

   .
2. Write

   FINDINGS.md

   using the schema in File schemas. Frontmatter:

   created

   and

   last_verified

   = today;

   status: active

   ;

   sources

   from the subagent return;

   raw:

   omitted (no raw yet);

   related: []

   unless cross-links apply.
3. Read

   INDEX.md

   , append a row: topic, path, today's date, a specific one-liner.

1. Read the existing

   FINDINGS.md

   .
2. Update frontmatter:

   last_verified

   = today; append new sources.
3. Apply the subagent's

   ## Supersedes

   list: move each named claim from

   ## Findings

   to

   ## Discarded approaches

   with date + reason. See Conflict handling.
4. Update / extend

   ## Findings

   with new claims.
5. Append a

   ## Timeline

   entry summarizing the change.
6. Read

   INDEX.md

   , update the row's

   Last verified

   column. Update the one-liner if the picture has changed.

tailwind-v5

2d-engines-clonable

orm-comparison-2026

1. Decide path first. Read

   INDEX.md

   . Does this paste extend an existing topic (merge mode), or is it a new topic (new entry mode)? Same decision as Retrieval phase 5.
2. Save the raw document verbatim to

   <root>/.research/<topic-slug>/raw/<YYYY-MM-DD>-paste.<ext>

   (preserve the original extension -

   .md

   ,

   .pdf

   ,

   .txt

   ,

   .html

   , etc.). If the user pasted text directly with no original file, default to

   .md

   .
3. Synthesize the content into the same shape the subagent would return (Summary / Findings / Sources). Citations to the raw file:

   [Source: raw/<filename>]

   .
4. Apply Storage (new entry path or merge path from Section 3) using the synthesized content. When writing the entry, include this raw in the

   raw:

   frontmatter list (path, note, added date).
5. Offer to delete the original file: "Save this as research and remove the original at

   <path>

   ?". Always ask. Never auto-delete.

raw:

raw/

• Always run

  date +%Y-%m-%d

  first. Pin the actual current year in WebSearch queries ("X 2026", "X latest 2026"). Don't trust your model's prior on what year it is.
• Prefer official release notes and changelogs over blog posts.
• When a source is older than 30 days on a fast-moving topic (npm packages, framework releases, AI tooling), treat it as a hint, not canon. Cross-check against newer sources.
• If an existing entry's

  last_verified

  is older than 30 days on a fast-moving topic, refresh before answering - don't quote a stale entry as current truth.

• Default = latest stable production release. That's what users should run unless they ask for something else.
• LTS when the project ships one and the user is on a long-lived stack (Node, Postgres, etc.).
• Nightly / pre-release / alpha / beta builds: only when the user explicitly asks ("what's coming in next release", "any unreleased features that solve X", "give me the bleeding edge"). Don't recommend nightly as a default - it's unstable and changes daily.
• Always state the version number you're recommending (e.g., "Drizzle ORM 1.4.2" not just "Drizzle ORM").

1. Official documentation / release notes / changelog
2. Maintainer blog posts and conference talks
3. GitHub issues, discussions, and pull request descriptions
4. Recent third-party benchmarks and reviews
5. Stack Overflow / Reddit / random blog posts

fetched: YYYY-MM-DD

• Every concrete claim has a

  [n]

  citation tied to a source URL in

  sources

  frontmatter
• If you don't have a source, write "no source - open question" and add it to

  ## Open questions

  . Never invent a URL or quote.
• When sources disagree, cite both and note the disagreement explicitly. Don't silently pick one.

1. Move the old claim to

   ## Discarded approaches

   with a one-line reason and date. Never delete silently.
2. If the same approach has failed twice or more, flag it loudly in

   ## Findings

   : "approach X has been tried and discarded N times - current working answer is Y". The point is to prevent re-trying refuted approaches in future sessions.
3. Update

   last_verified

   and append a

   ## Timeline

   entry summarizing the change.

• ...

• YYYY-MM-DD - initial entry

Notes on the schema:
- `raw:` is a list - one entry can accumulate multiple raw documents over time (e.g., user pastes a whitepaper, then later a different report on the same topic). Add new items, don't overwrite.
- Omit the `raw:` key entirely when there are no raw documents - don't leave an empty list.
- `related:` cross-links to other entry slugs. Use this when entries touch overlapping projects but answer different questions (e.g., `knowledge-graphs-comparison` and `mempalace-legitimacy` both mention mempalace but have different scopes - link them, don't merge them).

• Entry spam: one topic = one entry. Don't create separate entries for sub-aspects; nest them as sections.
• Researching the skill itself: don't write meta-entries about how research-memory works.
• Hallucinated sources: never invent URLs or quotes. If WebFetch failed, say so.
• Auto-delete on paste handler: always offer, never act.
• Silent supersede: any change to a prior conclusion goes through

  ## Discarded approaches

  +

  ## Timeline

  . Never overwrite.