--- name: research-handoff description: > Operator-confirmed emission gate: takes a completed research engagement (analysis slug or campaign dir) and proposes .work/ items grounded in its actionable findings. Each emitted item carries research_origin metadata plus a body citation back to the .research/ artifact. Silent no-op when .work/CONVENTIONS.md is absent. NEVER auto-fires — always operator-invoked and always asks before writing. --- # Research Handoff Arrow 2 of the research↔work handoff: a completed research engagement with actionable findings can **emit tracked `.work/` items**, operator-confirmed and gate-style. This skill is the emission gate. It is **operator-invoked and never auto-fires** — the `research-orchestrator` suggests it as a next step, but emission is always a deliberate operator act. The directionality invariant (non-negotiable): this gate writes **only to `.work/`**. It never writes into `.research/`. Research informs work; operational state never rewrites the research record (ARD SPEC §1/§4.6). Every step below that touches a file is either a read from `.research/` or a write to `.work/`. ## Phase 1 — Locate the source artifact(s) Resolve the operator's argument to one or more analysis artifacts: - **Slug** — look under `.research/analysis/` in all four sub-tiers: `positions/.md`, `briefs/.md`, `campaigns//parent.md` (or the campaign dir itself), `hypothesis/.md`. The slug is the `slug:` value in the artifact's YAML frontmatter (or the dir name for campaigns). - **Campaign dir** — if the argument is a path like `.research/analysis/campaigns//`, read `parent.md` as the synthesis. Read `dispatch.md` only when present: standalone-heavy campaigns use it as the registration fallback, but work-item-commissioned campaigns deliberately keep `.research/` as clean output substrate and carry registration on the commissioning item instead. From each resolved artifact, extract: 1. The actionable findings — sections or bullet points that represent recommendations, adoption proposals, hypotheses to validate, or implementation candidates. 2. The artifact's `output_kind` field when available (artifact frontmatter, or a campaign `dispatch.md` on the standalone-heavy path). Values that signal actionability: `adoption-recommendations`, `staged-hypothesis`, `recommendation`. Note it — it guides the proposed item kind. If no `output_kind` is present, do not fail: infer actionability from the artifact body, surface that inference in Phase 3, and let the operator confirm or skip. 3. The artifact's `slug` — this is the citation key for `research_origin:`. 4. The artifact file path — this is the body citation target. If no artifact is found at the resolved path, report clearly and stop. The finding stands in `.research/` and no `.work/` write is attempted. ## Phase 2 — Substrate presence check Check whether `.work/CONVENTIONS.md` exists in the working tree. **If `.work/CONVENTIONS.md` is absent:** report that the finding stands in `.research/` (path + slug) and that no operational substrate is present for emission. **Stop silently** — no `.work/` write is attempted, no error. The plugin's research capability is fully intact without `.work/`. This is the `repo-eval` precedent: "if no substrate exists, skip this phase silently." Only proceed to Phase 3 if `.work/CONVENTIONS.md` is present. ## Phase 3 — Propose and confirm via structured question tool Present the operator with: - A summary of the source artifact (slug, path, `output_kind`, brief description). - The list of actionable findings you extracted (numbered, one per proposed item). - The proposed item kind for each (story or feature, per scope; default to story for narrow/surgical findings, feature for findings that need a design pass). Ask: **where should these findings be filed?** Options (present all three, state the default): - **Backlog** (default, lowest commitment) — each finding becomes `.work/backlog/.md` for later scoping. Recommend this unless the operator has a specific reason to promote immediately. - **Active** — each finding becomes `.work/active/stories/.md` (narrow, surgical) or `.work/active/features/.md` (needs design pass), per scope. - **Skip** — leave findings in the report only, no `.work/` write. Honor the operator's choice exactly. If they select **skip**, stop here with no `.work/` write. **CRITICAL**: Do not write any `.work/` items before receiving confirmation. This skill never auto-writes. ## Phase 4 — Emit the confirmed items For each confirmed finding, write one item file. Follow the `.work/` substrate frontmatter convention (from `.work/CONVENTIONS.md`): ```yaml --- id: kind: story # or feature, per the operator's selection and finding scope stage: drafting tags: [] parent: null depends_on: [] release_binding: null gate_origin: null research_origin: created: updated: --- ``` **`research_origin: `** — set to the source artifact's slug (the citation key the `fields` feature added to the substrate schema). This is the machine-queryable link: `work-view --research-origin ` will find this item once the fields feature has landed. **Item body** — write the finding text (verbatim or lightly formatted for clarity) followed by a citation block: ``` ## Research grounding **Source**: `` (slug: ``) ``` **Tags**: derive from the finding's domain (e.g., `[adoption]`, `[security]`, `[testing]`, `[architecture]`). Use the source artifact's domain context as a guide. **Target path**: - Backlog (default): `.work/backlog/.md` - Active story: `.work/active/stories/.md` - Active feature: `.work/active/features/.md` Generate ids with the prefix `research-handoff--` (N = 1, 2, …) unless the operator provides their own id scheme. All writes target `.work/`. Nothing is written into `.research/`. ## Phase 5 — Commit and report Commit the emitted items: ``` research-handoff: filed items from (research_origin) ``` Report in conversation: - **Items filed**: count + each item's id and path. - **Next**: `/agile-workflow:scope` to cluster and prioritize the filed findings, or start an autopilot goal to drain them. ## Behavioral invariants - **No `.work/` write before confirmation.** Phase 3's structured question tool is mandatory. - **No `.research/` writes anywhere.** This gate is read-only against `.research/`; every write targets `.work/`. - **Silent no-op without `.work/CONVENTIONS.md`.** Phase 2 stops before any write attempt when the substrate is absent. - **One item per actionable finding** (default). Umbrella items only if the operator explicitly requests consolidation. - **`research_origin:` is always set** on emitted items (the schema field the `fields` feature ships). Body always carries a citation to the source artifact path + slug. ## Related - [`research-orchestrator`](../research-orchestrator/SKILL.md) — the engagement entry point that produces the `.research/` artifacts this gate consumes. When an engagement surfaces actionable output, the orchestrator suggests running `/agentic-research:research-handoff `. - `docs/HANDOFF.md` — the authoritative contract document for the research↔work pairing; Arrow 2 is this skill. - `.work/CONVENTIONS.md` — the substrate frontmatter contracts; governs the emitted item shape. - `work-view --research-origin ` — queries emitted items by their source engagement once filed.