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:

The reason to treat latent gaps as first-class: a spec that says "fast" or "good UX" hasn't been answered just because nothing was explicitly flagged. Planning will trip over those same words. Close them here.

Before dispatching research, show the combined list to the user in one message — "here's what I'm planning to close" — and let them add, remove, or defer items. Don't ask permission one-by-one; that's the proposal step.

Dispatching research

Each gap gets exactly one research task. Classify each task first — the type determines which tools the research needs:

With subagents (preferred)

When the Task tool (or equivalent subagent tool) is available, dispatch each research task as an independent subagent — all in the same turn, so they run in parallel. Each subagent gets its own context window, which matters: gaps often come with large supporting context (the spec, the codebase) that you don't want crammed into a single conversation.

See references/subagent-prompts.md for the prompt templates (one per task type).

The research return must be structured: recommended answer, 1–2 alternatives with why rejected, and concrete evidence (file:line citations, URLs, or references to existing spec sections). Cap each return at ~300 words — you want decisions, not transcripts.

Without subagents

If no subagent tool is available, do the research yourself, one question at a time. Work in cheapest-first order: codebase questions, then external, then tradeoffs, then scope/policy. Produce the same structured proposal for each. This is slower but never leaves gaps unresolved.

Proposing answers

Present proposals one at a time. For each:

• The gap — restated in one line
• Recommended answer — your best call, with WHY
• Alternatives — 1–2 credible options and why they were rejected
• Evidence — file:line citations, URLs, or references to decisions already in the spec

The user can accept, revise, or reject. Follow the thread if they want to discuss; move on once decided.

Order matters. Resolve in this rough sequence:

1. Codebase-reality gaps first (they may inform design tradeoffs)
2. Policy/scope gaps second (they shape everything downstream)
3. Format/presentation gaps last (they depend on the above)

When a gap can't be resolved without input only the user has (budgets, stakeholder preferences, unstated constraints), don't guess — ask directly. It's cheaper than proposing the wrong answer and unwinding it.

Rewriting the spec

As decisions land, migrate them to where they belong: