Resolve Beagle

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)

If the agent supports subagents, 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:

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
• No new externally-facing surface (API surface, command, endpoint, exported contract) without a named consumer — name it or move it to Future Considerations
• Any existing upstream/downstream pipeline mechanism that transforms the feature's data is recorded as a Key Decision tagged needs-spike-before-planning, not left unexamined

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.

Subagent Prompt Templates

Use these when dispatching research tasks to subagents. One task per subagent. Launch all subagents in a single turn so they run in parallel.

Every template ends with the same return format — a structured proposal the orchestrator can drop directly into the spec. Don't let subagents return free-form prose; decisions are the deliverable, not transcripts.

Return format (shared across all templates)

Every subagent must return exactly this structure, ~300 words max:

## Recommended answer
<one-sentence answer, then a short paragraph on WHY>

## Alternatives considered
- <alternative 1> — rejected because <reason>
- <alternative 2> — rejected because <reason>

## Evidence
- <file:line citation, URL, or reference to an existing spec section>
- <additional citations as needed>

## Open sub-questions (if any)
- <anything the subagent couldn't resolve and needs the user or orchestrator to decide>

If the subagent cannot produce a recommendation with evidence, it should say so explicitly in "Open sub-questions" rather than guess.

---

Template: Codebase pattern

Use when the question is about how the existing codebase works — an API, a pattern, a file layout, a convention that the spec references.

You are researching one question for an in-progress project spec.

Spec path: <absolute path>
Question: <the exact open question, verbatim>

Your job: read the relevant code and return a structured proposal answering the question. Use Grep, Glob, and Read. Do not modify any files.

Scope hints:
- <file/dir hints from the spec, if any>
- <reference points mentioned in the spec>

Return in this exact format:

## Recommended answer
<one-sentence answer, then a short paragraph on WHY — grounded in what you found>

## Alternatives considered
- <alt 1> — rejected because <reason, citing code>
- <alt 2> — rejected because <reason, citing code>

## Evidence
- <file:line> — <one-line description of what's there>
- <file:line> — <one-line description>

## Open sub-questions
- <anything that needs user input or is blocked>

Cap the return at ~300 words. Cite file paths and line numbers. Decisions, not transcripts.

Template: External / API

Use when the question is about an external system — a framework's capabilities, an SDK's API, a tool's behavior.

You are researching one question for an in-progress project spec.

Spec path: <absolute path>
Question: <the exact open question, verbatim>

Your job: use web search and page fetch (if web access is available) to find authoritative answers — official docs, source repositories, maintainer statements. Avoid blog posts and secondhand summaries.

Focus area: <framework / SDK / tool name>
Why it matters: <one-line context pulled from the spec's Problem Statement or Key Decisions>

Return in this exact format:

## Recommended answer
<one-sentence answer, then a short paragraph on WHY — grounded in what the official source says>

## Alternatives considered
- <alt 1> — rejected because <reason, citing source>
- <alt 2> — rejected because <reason, citing source>

## Evidence
- <URL> — <one-line description of what it says>
- <URL> — <one-line description>

## Open sub-questions
- <anything version-specific, ambiguous, or that needs user confirmation>

Cap the return at ~300 words. Prefer primary sources. Decisions, not transcripts.

Template: Design tradeoff

Use when the question is a product/design judgment call with no single "right answer" in the codebase or external docs — format decisions, deduplication heuristics, UX structure.

You are researching one question for an in-progress project spec.

Spec path: <absolute path>
Question: <the exact open question, verbatim>

Your job: reason about the tradeoff and produce a concrete recommendation grounded in the spec's own Core Value, Problem Statement, and Key Decisions. Reference the spec heavily — the right answer usually already lives implicit in the rest of the document.

Do NOT propose implementation details. The answer goes into the spec as a WHAT/WHY decision, not a HOW.

Return in this exact format:

## Recommended answer
<one-sentence answer, then a short paragraph on WHY — explicitly citing which spec section supports the choice>

## Alternatives considered
- <alt 1> — rejected because <reason, ideally citing a spec section it would undermine>
- <alt 2> — rejected because <reason>

## Evidence
- Spec section "<section name>" — <what it says that informs this>
- <additional analogies or reference points if relevant>

## Open sub-questions
- <anything that needs the user's judgment (preferences, budgets, unstated constraints)>

Cap the return at ~300 words. Ground the call in the spec. Decisions, not transcripts.

Template: Scope / policy

Use when the question is about inclusion/exclusion — what routes where, what's covered, what's explicitly out.

You are researching one question for an in-progress project spec.

Spec path: <absolute path>
Question: <the exact open question, verbatim>

Your job: recommend the scope/policy answer that best preserves the spec's Core Value and is consistent with its existing Out-of-Scope rationale. Read the spec end-to-end before deciding — scope answers regress fast if you only look at the local question.

Do NOT propose implementation details. The answer goes into the spec as a WHAT/WHY decision.

Return in this exact format:

## Recommended answer
<one-sentence answer, then a short paragraph on WHY — showing it aligns with Core Value and existing Out-of-Scope reasoning>

## Alternatives considered
- <alt 1> — rejected because <reason, ideally showing it conflicts with a stated constraint>
- <alt 2> — rejected because <reason>

## Evidence
- Spec section "Core Value" — <relevant phrase>
- Spec section "Out of Scope" — <relevant rationale>
- <other spec sections as needed>

## Open sub-questions
- <anything that needs user input on future intent>

Cap the return at ~300 words. Consistency with the spec matters more than novelty. Decisions, not transcripts.