resolve-decisions

name

resolve-decisions

description

Walk the PRD's unresolved items — `[NEEDS DECISION]` markers, `## Open Questions`, and missing acceptance-criteria or verification fields — and drive each one as a Q&A turn with the user, proposing concrete options when possible and applying the chosen answer with `anvil prd resolve-decision`. Use this skill when `anvil prd find-decisions` reports unresolved items, or when other skills (prd, plan) detect decisions blocking progress.

Resolve Decisions — Walk Open Items as Q&A

Turn every [NEEDS DECISION] marker, unresolved ## Open Question, or missing acceptance-criterion into a one-question conversational turn — propose options when the surrounding context lets you, accept the user's pick, and apply the answer with anvil prd resolve-decision. The agent does the framing and the typing; the user does the deciding. Let the CLI own the file write: it locates the decision by id, rewrites the right span without touching unrelated content, and records the resolution as an event.

The anti-pattern this skill exists to prevent: handing the user a list of "open questions to resolve in your editor first" and then waiting. An LLM's strength over a CLI is turning blocked on a decision into let me ask you the right question. Pasting a to-do list of unresolved decisions is the same failure mode as pasting a to-do list of CLI commands.

---

When to Use

• After anvil prd parse succeeds and the agent notices unresolved items (prd skill Step 3 routes here when find_decisions returns non-empty).
• Before anvil plan runs, when find_decisions reports [NEEDS DECISION] markers or unresolved Open Questions that would shape task generation (plan skill Step 0 routes here).
• When the user explicitly asks to "resolve open questions", "answer the NEEDS DECISION items", or "fill in the missing acceptance criteria".
• When anvil review tasks blocks tasks for missing acceptance criteria or verification commands — those become missing_field decisions this skill can drive Q&A on, instead of asking the user to re-edit the PRD by hand.

Do not use this skill to author requirements from scratch — use start-prd. Do not use this skill to score or expand tasks — that is the plan skill's job. Do not use this skill to make apply --approve decisions — that is the finish skill's gate.

---

Prerequisites

The project must be initialized and the PRD must parse cleanly. Confirm init first, then parse:

anvil status >/dev/null 2>&1 || echo MISSING
anvil prd parse 2>&1 | tail -3

If anvil status reports MISSING, the project is not initialized — route back to the bridging skill rather than guessing a path. State lives in the HOME workspace by default (anvil status prints the resolved state directory on its Path: line), so never reach for a literal in-repo .anvil/... file.

The detector lives in the anvil.planning.decisions module; the CLI surface is anvil prd find-decisions (read-only scan) plus anvil prd resolve-decision (writes the answer back); the MCP equivalent of the scan is the find_decisions tool. Confirm any command with anvil <cmd> --help.

---

Workflow

Step 1 — Scan for unresolved items

Drive the scan yourself; do not tell the user to run the CLI. Invoke anvil prd find-decisions (or the find_decisions MCP tool when the runtime exposes it) and parse the result. Surface a one-paragraph summary inline:

I found N unresolved items in the PRD:

• X [NEEDS DECISION] markers (inline, often tied to specific requirements or features)
• Y ## Open Questions items (top-level uncertainties about scope or approach)
• Z missing fields on tasks (acceptance criteria or verification commands the review gate requires)

Want me to walk them one at a time? (yes / not yet / show me the list first)

On show me the list first, present the full list compactly (one line per decision: id, kind, location, first 60 chars of text). Then re-ask "ready to walk them?"

On not yet, stop. Confirm the items are visible in anvil prd find-decisions for later.

On yes, proceed to Step 2.

Step 2 — Drive each decision as one Q&A turn

Iterate the decision list in the order the detector returned (it is deliberately stable: needs_decision first, then open_question, then missing_field). For each item, present the question conversationally and propose concrete options when the surrounding context allows you to. This is the LLM-leverage moment — turn an unresolved item into a multiple-choice question whenever possible.

For a needs_decision marker:

ND-001 — Summary section The PRD says: "The system must validate inputs [NEEDS DECISION: which encoding?]."

Based on the surrounding paragraph (about validating incoming HTTP requests), three reasonable answers:

1. UTF-8 only — strict, fails on anything else. Simplest. Best if all known clients send UTF-8.
2. UTF-8 with Latin-1 fallback — pragmatic for legacy clients. Slightly more code.
3. Detect with chardet and accept any standard encoding — most permissive; adds a dependency.
4. Other (describe)

Pick (1 / 2 / 3 / or describe your own).

On the answer, apply it with anvil prd resolve-decision, passing the decision id from the scan and the chosen answer. The CLI does the inline rewrite for you (it replaces [NEEDS DECISION: which encoding?] with the resolution and leaves the rest of the sentence verbatim), saves the PRD wherever it lives, and records a prd.decision_resolved event:

anvil prd resolve-decision ND-001 --resolution "UTF-8 only"

The CLI echoes the rewrite so you can confirm it landed, then move on:

Resolved ND-001 (needs_decision) in /…/.anvil/prd.md.
  section:  Requirements (line 13)
  before:   - R001: The system must validate inputs [NEEDS DECISION: which encoding?].
  after:    - R001: The system must validate inputs UTF-8 only.
  recorded: E000010 (prd.decision_resolved)
Run `anvil prd parse` to refresh state.db.

For an open_question item:

OQ001 — Open Questions item 1 "Which serialization format should we use for the on-disk packet cache?"

Three reasonable answers based on the rest of the PRD:

1. JSON — human-readable, no extra dependency, fine for our packet sizes.
2. MessagePack — ~3× smaller on disk, requires msgpack dep.
3. Protocol Buffers — schema enforcement + cross-language; overkill for this use case.
4. Defer to v2 — note as a non-goal for now.

Pick (1 / 2 / 3 / 4 / or describe).

On the answer, apply it with anvil prd resolve-decision. The CLI moves the resolved item out of ## Open Questions and into a ## Decisions section (creating that section if it does not exist) and records the event, so you do not edit the file by hand:

anvil prd resolve-decision OQ001 --resolution "MessagePack — ~3x smaller on disk; accepted the msgpack dependency over JSON's bigger files."

The CLI writes the ## Decisions entry as - **<question>** → **Decision:** <resolution> and echoes what changed:

Resolved OQ001 (open_question) in /…/.anvil/prd.md.
  section:  ## Open Questions → ## Decisions
  before:   - Which serialization format should we use for the on-disk packet cache?
  after:    - **Which serialization format should we use for the on-disk packet cache?** → **Decision:** MessagePack — ~3x smaller…
  recorded: E000011 (prd.decision_resolved)
Run `anvil prd parse` to refresh state.db.

This preserves the audit trail — future re-reads can see what was unclear at draft time and what was decided. If the resolution materially affects a requirement or feature, surface that to the user inline: "This decision also implies R007 should change to read X instead of Y; want me to update R007 too?", then resolve the corresponding [NEEDS DECISION] marker (or, if there is none, ask the user to revise that requirement directly).

For a missing_field item:

MF-T012-AC — T012 acceptance criteria Task T012 ("Implement retry-with-backoff for transient HTTP failures") has no acceptance criteria. The review gate requires at least one.

Based on the task description, four candidate criteria:

1. On 429 / 503, the client retries up to 3 times with exponential backoff (1s / 2s / 4s).
2. On 500-class errors, the client logs the failure and re-raises after retries are exhausted.
3. On 4xx (non-429), the client does NOT retry and surfaces the error.
4. None of these — let me describe my own.

Add (1) only, (1+2), (1+2+3), or (4) describe?

On the answer, apply each chosen bullet with anvil prd resolve-decision against the missing-field id from the scan (MF-T012-AC for acceptance criteria, MF-T012-V for verification). The CLI appends the bullet under the task's ### T012: block, so call it once per bullet:

anvil prd resolve-decision MF-T012-AC --resolution "On 429/503, the client retries up to 3 times with exponential backoff (1s/2s/4s)."

Same pattern for a missing verification command (MF-T012-V) — propose 2-3 candidate pytest / shell invocations based on the likely files, accept the pick, and resolve each one. The CLI records a prd.decision_resolved event per call and echoes the edit.

On any decision the LLM cannot propose options for (the context is too thin, the question is too open), do not invent options. Ask the open-ended question and accept whatever answer the user gives:

OQ003 — Open Questions item 3 "What is the upper bound on payload size?"

I do not have enough context to propose options here — what bound do you want?

Step 3 — Re-parse after the batch is resolved

Each anvil prd resolve-decision call already edited the PRD and recorded an event, but it does not refresh state.db; that is what anvil prd parse does. Once every decision is answered (or the user explicitly skips the remaining ones), drive a re-parse yourself so the canonical state catches up:

All N decisions have been applied to the PRD. Re-parsing to refresh state.db — ready? (yes / wait, I want to re-read the PRD first)

On yes, invoke anvil prd parse. Surface the new counts. If the re-parse surfaces fresh errors, drive a fix immediately — do not hand the user a "go fix it in the editor" message. Read the parse error, identify which span is wrong, and resolve it with anvil prd resolve-decision (or, if the break is outside any decision span, propose the corrected text and apply it once the user confirms).

After re-parse, optionally re-run anvil prd find-decisions to confirm the unresolved count is 0 (or to surface anything the resolution exposed — e.g., a needs_decision rewrite that introduced a new field with empty acceptance criteria).

Step 4 — Hand off to the next skill

Once the PRD is fully resolved:

All decisions resolved. The PRD is ready for the next step. What's next?

1. Continue into /anvil:plan — generate features and tasks now that the PRD is unambiguous.
2. Review the PRD one more time first — I'll open it inline so you can scan the ## Decisions section.
3. Stop here — we're done with the resolver; you'll drive plan later.

On 1, invoke the plan skill directly (do not paste anvil plan as a command for the user to type). On 2, show the relevant sections inline; when the user says "looks good," re-ask the next-step question. On 3, confirm and stop.

---

Anti-pattern to avoid

Ending the skill with a message like "OQ001 (success criterion) and OQ006 (time budget) should be resolved before planning. Open .anvil/prd.md in your editor to fix them, then re-run anvil prd parse and anvil plan." That handoff treats an unresolved decision like a known bug instead of a question the agent could have asked. The whole point of an LLM agent inside the conversation is that it can frame the right question with concrete options — pasting the list of unresolved items as a to-do is forfeiting that strength.

The rule: for every unresolved item, the agent generates the question and proposes 2-4 candidate answers (when context allows). The user picks. The agent applies the answer with anvil prd resolve-decision. No "open the editor" handoffs unless the user explicitly opts out.

When to actually hand off to the editor: if the user says "let me think about these — I'll edit them directly later," or if a decision is genuinely too cross-cutting to express as a single Q&A turn (e.g., "redesign the whole authentication architecture"). In those cases, list the unresolved items compactly, point the user at anvil prd find-decisions so they can re-surface the list later, and stop.

---

Decision-presentation discipline (canonical)

Whenever any anvil skill surfaces a multi-option choice to the user, present it as a structured Q&A turn, not as prose with bullets.

Use AskUserQuestion when running inside Claude Code. The labeled options become an explicit pick UI and the answer comes back as a known label, so the agent can act unambiguously. For other runtimes, fall back to explicit numbered prompts ("Pick 1 / 2 / 3").

Anti-pattern: ending a turn with paragraph-style alternatives that ask for a decision but don't pin down the answer shape. For example:

"Two options: Cut T014 (planner's recommendation). Cut T008 + T018 (distributed). My recommendation is the first. What's your call?"

Replace with a structured prompt so the answer is one of N labels and the agent knows exactly what to do next:

1. Cut T014 + trim T002 (planner's recommendation; lands at ~80h)
2. Cut T008 + T018 + trim T007 (distributed; keeps all features intact)
3. Defer T017 (Wasm network policy; affects F005)
4. Keep all tasks and accept the overrun

Pick 1 / 2 / 3 / 4 (or describe).

The rule applies across all skills: any time the agent could present 2+ options for the user to pick, use structured Q&A. Prose-with-bullets that lacks an explicit "pick N" prompt forces the user to type free-form intent the agent then has to interpret — wasted turn.

---

Composition with Other Skills

Position	Skill
Before this skill	prd Step 3 (after parse_prd succeeds) — soft-gates into resolve-decisions when find_decisions returns non-empty
Before this skill	plan Step 0 — soft-gates into resolve-decisions when [NEEDS DECISION] or unresolved Open Questions would shape task generation
After Step 4 (resolved)	plan — continue into task generation now that the PRD is unambiguous
If the user opts out	Return to whatever skill bridged here; proceed without resolving (the soft gate is by design)