research-gather
Skill0 starsChanged 4 months agoMITView on GitHub
Phase 1 of 3 in the research chain (gather → synthesize → artifact). Collects raw material from user-provided sources — URLs, local docs, or topics — using the fetch tool (SSRF-safe) for remote content and explore-role subagents for local docs and broad exploration. This phase starts the durable chain run (state tracked by the chain tool). Trigger whenever the user wants to start a research run: "research-gather", "start a research chain", "phase 1 of research", "research this topic", "gather sources on X", or standalone "research".
In this repository21 other files it gives its agents.
- bughunt-diagnoseSkill
- bughunt-fixSkill
- bughunt-reproSkill
- bughunt-verifySkill
- feature-ship-buildSkill
- feature-ship-reviewSkill
- feature-ship-shipSkill
- feature-ship-specSkill
- migrate-inventorySkill
- migrate-transformSkill
- migrate-verifySkill
- onboard-deepenSkill
- onboard-digestSkill
- onboard-mapSkill
- release-bumpSkill
- release-changelogSkill
- release-publishSkill
- release-tagSkill
- release-verifySkill
- research-artifactSkill
- research-synthesizeSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 29
All chain state is managed by the chain tool: authoritative JSON at .pi/fairy-tales/chains/research/state.json with a human-readable …
- Very specific: line 38
Call the chain tool with action: "status", chain: "research":
- Very specific: line 40
If an active run exists, a research run is already mid-flight (the status shows its current phase — a legacy .research-state.md from an …
- Very specific: line 45
If the tool reports the chain is locked by another session, abort and tell the user.
- Very specific: line 47
If there is no run, or the last run is complete/abandoned, start fresh: action: "start", chain: "research", task: "<research question / …
- Very specific: line 78
If a returned quest is already done (crash-resume case), reuse its stored result.
- Distinctive: line 94
Call the chain tool:
- Distinctive: line 112
After completing this phase, output exactly:
- Distinctive: line 117
Do not start the next phase.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Research: Gather
Chain version: 2 (durable state contract — see docs/STATE-CONTRACT.md)
Phase 1 of 3: research-gather → research-synthesize → research-artifact
Overview
Entry point of the research chain. Takes the user's research question plus any
provided sources (URLs, local file/doc paths, or topics to explore) and collects raw
material: per-source notes, key quotes, and links.
Fetches remote content with the fetch tool (SSRF-safe) and dispatches explore-role subagents to read local docs and codebase material, so the gather pass covers both "on the web" and "already on disk" sources in parallel.
All chain state is managed by the chain tool: authoritative JSON at
.pi/fairy-tales/chains/research/state.json with a human-readable state.md
projection beside it. Never create or edit state files by hand, and never create lock
files — the tool locks for you.
Workflow
Step 1 — Start the run (entry phase)
Call the chain tool with action: "status", chain: "research":
- If an active run exists, a research run is already mid-flight (the status shows
its current phase — a legacy
.research-state.mdfrom an older version is imported automatically). Show the user the status and ask whether to resume from the current phase (run that phase's skill) or discard it (action: "abandon") and start over. Do not silently overwrite. - If the tool reports the chain is locked by another session, abort and tell the user;
a dead session's lock can be cleared with
action: "unlock". - If there is no run, or the last run is complete/abandoned, start fresh:
action: "start", chain: "research", task: "<research question / topic>". Note therunIdin the response — it keys this run's quest dedupe keys.
Step 2 — Identify sources
Clarify the research question and enumerate the sources to cover: explicit URLs the user gave, local doc/codebase paths, and any topics that need open-ended discovery.
Step 3 — Fetch remote sources
For each URL, use the fetch tool (SSRF-safe) to retrieve the content — it blocks requests to private/internal/link-local IP ranges and unsafe redirect targets, so it is the correct way to pull content from user-supplied or untrusted URLs. Never fetch external URLs any other way in this phase.
Step 4 — Explore local material via durable quests
For local docs, codebases, or open-ended topics that need discovery rather than a direct URL, dispatch explore-role subagents — one per source cluster or research sub-question. Because this exploration can be long-running and must survive a session restart, use the quest tool rather than a bare agent call:
questactionenqueuewithrole: "explore", a self-contained task (the source cluster or sub-question, and what to report back), and:dedupeKey: "research/<runId>/gather/<cluster>"(a descriptive id for the source cluster/sub-question) — re-running a crashed phase returns the same quest instead of duplicating exploration;chain: { chain: "research", runId: "<runId>", phase: "gather" };retainUntilConsumed: true.
- Issue independent clusters'
enqueuecalls in one message so they run in parallel. - If a returned quest is already
done(crash-resume case), reuse its stored result; otherwisequestactionrunwith itsidand collect the result. After extracting what's needed into chain state (Step 6),questactionconsumeeach quest byid.
Step 5 — Capture per-source notes
For every source (remote or local), record:
- Source name/URL/path
- A short summary of what it says
- Key quotes, captured verbatim with attribution
- Any links or citations found within it worth following up
Step 6 — Complete the phase
Call the chain tool:
action: "complete-phase", chain: "research", phase: "gather",
summary: "raw material gathered from N sources (M remote via fetch tool, K local via explore quests); scope chosen, sources skipped and why",
data: {
"sources": [
{ "source": "<name/URL/path>", "summary": "<short summary>", "quotes": ["<quote>", "..."], "links": ["<link>", "..."] }
]
},
artifacts: { "exploreQuests": "<quest ids>" }The tool validates this is the current phase, advances the run to synthesize, and
rewrites the JSON + markdown projection atomically.
Handoff
After completing this phase, output exactly:
Phase 1 complete. Chain state updated (
.pi/fairy-tales/chains/research/state.json). Run/research-synthesizeto begin Phase 2.
Do not start the next phase. Do not offer to continue. Output only the handoff line and stop.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

