/resolve-beagle

name: resolve-beagle
description: "Use as the follow-up to brainstorm-beagle when a spec has an Open Questions section (or quietly carries latent gaps) that need closing before planning or implementation can begin. Triggers on: \"resolve the open questions\", \"close the gaps in this spec\", \"research the open items\", \"finalize my spec\", \"make this spec implementation-ready\", \"answer the TBDs\". Also triggers whenever the user points at a brainstorm-beagle spec and asks for research, proposals, or answers to unresolved items. Orchestrates parallel research subagents when available (falls back to inline sequential research otherwise), proposes answers one at a time for user approval, then rewrites the spec in place so it arrives at planning with no known gaps. Does NOT write code, design implementation, or create plans — it only produces a complete spec."

Resolve: Close Spec Gaps

Take a spec produced by `brainstorm-beagle` and close its remaining gaps — both the explicit Open Questions and the latent ones the self-review missed — by researching, proposing answers, and rewriting the spec in place.

The terminal state is a spec with no known open questions and no placeholder requirements. Planning can start immediately after.

<hard_gate> This skill does not write code, scaffold projects, design architecture, or create implementation plans. It only edits the spec document. "Answering an open question" means proposing a WHAT/WHY answer with rationale — never a HOW. If a question turns out to require implementation design, defer it with a note and move on. </hard_gate>

Gates (pass before next step)

Objective pass conditions so steps are not skippable by assertion alone:

1. **Spec located** — The target file path is known and `Read` succeeds (or the user supplied a valid path after you listed 3–5 recent `docs/specs/` candidates). 2. **Gap list published** — One message lists every explicit Open Question bullet **and** each latent gap you will treat as in-scope. **Do not dispatch research** until the user adjusts the list (add/remove/defer) **or** explicitly tells you to proceed with that list. 3. **Research artifact per gap** — Before you present a proposal for gap *G*, you have a structured note for *G*: recommended answer, 1–2 rejected alternatives with reasons, and evidence (file:line, URL, or in-spec citation). No proposal without that artifact. 4. **One proposal queue** — Do not open the next gap’s proposal until the current gap has a clear outcome (accepted, revised wording applied, rejected with what happens next, or deferred with reason). 5. **Rewrite reconciled** — After editing, you read the full spec once and resolve cross-section contradictions; then run the self-review checklist from `../brainstorm-beagle/references/spec-reviewer.md` with failures fixed in-session unless the user opts for a follow-up pass. 6. **Commit** — No `git commit` unless the user answered yes to the commit prompt in § Committing.

Workflow

1. **Locate the spec** — explicit path from the user, or the most recent file in `docs/specs/` 2. **Extract gaps** — parse Open Questions *and* audit for latent issues (placeholders, vague requirements, missing rationale, contradictions) 3. **Show the gap list** — present everything you plan to close in one summary so the user can add or remove items before research starts 4. **Dispatch research** — one task per gap, in parallel via subagents when available; otherwise sequentially inline 5. **Propose answers** — one proposal at a time, with recommendation + alternatives + evidence 6. **Rewrite the spec in place** — migrate resolved items to the right sections; nothing silently dropped 7. **Self-review** — same checklist `brainstorm-beagle` uses (see `../brainstorm-beagle/references/spec-reviewer.md`) 8. **Ask about committing** — prompt the user whether to commit the edit; don't commit unprompted

Locate spec → Extract gaps → Show list ──→ User adds/removes
                                          → Dispatch research (parallel if possible)
                                          → Propose answers (one at a time)
                                                → User decision → next
                                          → Rewrite spec in place
                                          → Self-review (fix inline)
                                          → Ask about committing

Locating the spec

If the user gave a path, use it.

Otherwise, list the 3–5 most recently modified files in `docs/specs/` and ask: "Work on `<most recent>`, or another one?" Don't scan the whole directory tree — specs are top-level per `brainstorm-beagle`'s convention.

If no spec directory exists, ask the user for the path.

Extracting gaps

Two categories count as gaps:

**Explicit gaps** — every bullet under the spec's `Open Questions` heading is one research task.

**Latent gaps** — issues that slipped past the brainstorm's self-review. Scan the spec for:

| Problem | What it looks like | |---------|-------------------| | Placeholder | TBD, TODO, "to be determined", ellipsis used as content | | Vague requirement | "fast", "simple", "good", "user-friendly", "intuitive" — nothing to verify against | | Missing rationale | Constraint or Out-of-Scope item with no "why" | | Contradiction | Requirement conflicts with another requirement, with a constraint, or with Out of Scope | | Untestable success | No observable way to verify the requirement was met | | Implementation leakage | A requirement prescribes HOW instead of describing WHAT | | Unconsumed surface | A must-have introduces new externally-facing surface (API surface, command, endpoint, exported contract) that nothing else in the spec consumes | | Unresolved composition | An existing mechanism sits upstream/downstream in the same data pipeline and transforms (truncate, filter, buffer, reorder, dedupe) the data the feature depends on, but its composition with the feature is left unexamined |

The