Resolve: Close Spec Gaps

Take a spec produced by

brainstorm-beagle

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>

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/

<most recent>

brainstorm-beagle

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

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:

--start-at

SKILL_MAP

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

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:

deferred: <reason>

Two rules that matter:

• Never silently drop an Open Question. Either resolve it, migrate it with rationale, or explicitly defer it with a reason. Dropping a question without a trail is how specs regress between sessions.
• Rewrite the whole spec, not just the touched sections. Changes ripple: a new Key Decision may contradict an old Requirement, a resolved Open Question may invalidate a Constraint. Read the spec end-to-end after edits and reconcile.

Self-review

Run the checks from

../brainstorm-beagle/references/spec-reviewer.md

• No placeholders
• No contradictions
• No implementation leakage
• All requirements testable
• Constraints and Out-of-Scope items have rationale

Fix anything that surfaces inline before handing back to the user. If new gaps appear during the rewrite (they sometimes do), add them to a "new gaps surfaced" list and ask the user whether to resolve them now or leave for a later pass.

Committing

After the rewrite, summarize and ask:

"Spec updated. Resolved N explicit questions and M latent gaps. Want me to commit this as

docs: resolve open questions in <topic> spec

?"

If yes, commit. If no, leave the working tree for the user. Do not commit unprompted — the user may want to review the diff first or bundle it with other changes.

Key Principles

• Close the loop. The goal is a spec with nothing unanswered that blocks planning. Half-resolved is worse than clearly deferred.
• One research task per gap. Don't blur tasks together — it makes the proposal step harder to review and weakens the evidence trail.
• Evidence over opinion. Every proposal cites something — a file, a URL, or an existing spec decision. "I think" is not enough.
• Still WHAT, not HOW. Answers land as decisions in the spec, not as implementation designs. If an answer requires implementation thinking, defer it.
• Defer honestly. A question too expensive to answer now stays an Open Question with a one-line reason. Better to admit a known gap than paper over it.
• Parallelize when you can. Subagents run in isolation — fan out aggressively. Sequential research is the fallback, not the default.
• Don't interrupt unnecessarily. Show the gap list once, then only stop the user for decisions that need human judgment.