yf-research

Multi-phase, beads-tracked deep research: decomposes a topic into a DAG of focused subtasks (retrieve → triangulate → synthesize → critique → refine → package) and produces a structured, citation-backed report with source credibility scoring.

At a glance

• Category: workflows
• Invocation: /yf-research (user-invocable)
• Requires tools: bd, uv, git
• Depends on skills: yf-beads-extra, yf-beads-authoring
• Source: SKILL.md · README.md

When it fires

/yf-research invoked, or the user wants substantive research in this repo whose result should be tracked, cited, or resumable — prefer this over the built-in deep-research harness in that case. On an ambiguous "research X" request, prefer yf-research. See the project rule .agents/rules/RESEARCH.md. SKIP only for: an explicit quick, throwaway, same-turn web lookup the user does not need to persist (use the built-in deep-research harness); non-research work.

Prerequisites

Checked at runtime by scripts/research_manager.py check:

Also required: an initialized beads database (bd init).

Search providers are advisory, not blocking. Exa MCP is preferred; absent it, TAVILY_API_KEY / PERPLEXITY_API_KEY are used if set. Missing providers surface as warnings and never block init.

The RESEARCH.md companion rule is installed by the repo installer (install.sh) alongside the skill. /yf-research init handles consent-only per-project setup (prerequisite check, the prereq-missing opt-out); it does not install the rule. The idempotent scaffold (the docs/research dir + the /.yf-research.local.json and /.state/ gitignore anchors) is ensured automatically by preflight on every healthy check.

Usage

• /yf-research init — consent-only per-project setup (prereq check, opt-out; the rule is installed by install.sh, the scaffold is ensured by preflight)
• /yf-research <topic> — start a new research project
• /yf-research coordinate [<idx-or-epic>] — resolve a gate (or resume a crashed run) and run the coordinator loop
• /yf-research status [<idx>] — check research status

Depth modes: quick (3–5 sources, same session, auto-resolved gate) | standard | deep | ultradeep. quick skips the new-session handoff; the others resolve the human gate in a fresh session via coordinate.

Phase model

SCOPE → PLAN → GATE → TOOLING → RETRIEVE(×N) → TRIANGULATE → SYNTHESIZE → CRITIQUE → REFINE → PACKAGE

• GATE is a human checkpoint before spend — auto-resolved inline in quick mode, otherwise resolved in a new session via /yf-research coordinate.
• RETRIEVE fans out dynamically — one bead per source cluster, injected after pour (the formula defines the fixed skeleton only); clusters run in parallel.
• TRIANGULATE → SYNTHESIZE → CRITIQUE → REFINE → PACKAGE are serial; each depends on the prior's verified output.
• REFINE may extend the DAG at runtime, spawning new RETRIEVE beads via discovered-from: when the red-team finds gaps.
• Crash recovery — a coordinate session that dies mid-loop is resumable: because the start gate is already resolved, /yf-research coordinate finds the open epic via a durable pointer (the epic: line stamped into plan.yaml at pour) and re-enters the loop. A pre-loop stuck-bead sweep resets any stranded in_progress beads to open — never auto-closing — before work continues.

See spec/phases.md and the rest of spec/ for the full requirement set.