fix(explore): capture branch runs `openspec new change` without the first-write confirmation the same skill requires

[choi138]

fix(explore): capture branch runs openspec new change without the first-write confirmation the same skill requires

Version: @fission-ai/openspec@1.13.0 (also present on main as of 2026-09-10)

Follow-up to #1715 / #1716, which added the explicit first-write confirmation to explore mode. The capture branch appears not to have been brought under that rule.

Summary

skills/openspec-explore/SKILL.md states twice that the agent must get an explicit yes/no confirmation, in a separate user message, before its first write-capable action — naming openspec new change as an example. The capture branch in the same file then instructs the agent to transition "seamlessly" into running openspec new change and creating artifacts, with no confirmation step.

The two readings produce opposite behavior for the same user turn, and the file does not say which one governs.

The conflict

Rule, L14:

Before the first write-capable action, name the artifacts or files you would change and what you would do, ask a direct yes/no question, and wait for the user's confirmation in a separate message. Confirmation covers only the scope you described; ask again before expanding it. For a new change, scaffold it first as described below.

Rule restated in Guardrails, L338:

Don't auto-capture - Offer to save insights, don't just do it. Read-only commands and tools need no confirmation. Before the first write-capable action—including openspec new change or another command that writes files—name the artifacts or files and proposed changes, ask a direct yes/no question, and wait for explicit confirmation in a separate user message.

Capture branch, L144-L146:

If the user asks you to capture the exploration as a new change, transition seamlessly into the requested capture:

1. Run openspec new change "<name>" (with --store <id> when applicable) before creating any artifacts.

Steps 2-4 (L147-L149) then create artifacts in dependency order, still with no confirmation gate.

Why it is genuinely ambiguous

Both readings are defensible from the text as written:

• Capture request = the confirmation. The user did ask for a change, so requiring a second yes/no is redundant, and "seamlessly" says so.
• Capture request ≠ the confirmation. L338 requires the confirmation to be a separate user message, and L14 requires it to name the artifacts or files — a bare "capture this as a change" does neither, and cannot, since the artifact set is only known after openspec status. L42 adds "Accepting an answer or a batch of recommendations is not permission to write."

L14's own closing sentence — "For a new change, scaffold it first as described below" — points at the capture branch, which makes it read as if scaffolding is exempt, while L338 names openspec new change as exactly the thing that is not exempt.

In practice the agent's behavior varies by which passage it weighs, so the same request either writes .openspec.yaml plus several artifacts immediately, or stops and asks.

Impact

The capture branch is the one path in explore mode that writes files, so whichever way it resolves determines whether the #1716 guarantee holds at all. Left ambiguous, explore mode's "Don't auto-capture" guardrail is unenforceable in the only case where it applies.

Suggested fix

Either resolution works; the file just needs to pick one.

Option 1 — capture request counts as confirmation (keeps the current flow). Say so explicitly at L144 and carve it out of the rule:

If the user asks you to capture the exploration as a new change, that request is
the confirmation required above for scaffolding the change and creating the
artifacts they named. Transition into the requested capture. Ask again before
creating any artifact they did not ask for.

Option 2 — require the confirmation (keeps the rule uniform). Insert a step before L146:

1. Name the change you would scaffold and the artifacts you would create, ask a
   direct yes/no question, and wait for the user's confirmation in a separate
   message.
2. Run `openspec new change "<name>"` ...

Option 1 preserves the intent of "seamlessly" and is the smaller change. Option 2 is stricter and matches #1715's report more literally. I lean toward Option 1 with the explicit carve-out, since re-asking immediately after "capture this as a change" is the friction #1017 and the surrounding wording seem to be trying to avoid — but that is a call for the maintainers.

Whichever is chosen, src/core/templates/workflows/explore.ts needs the matching edit, per the file set in #1716.

Happy to open the PR once you pick a direction.

[clay-good]

Thanks for this — the analysis is exactly right, and laying out both options with the arguments for each is what made it quick to act on.

Went with your Option 1, and for your stated reason: re-asking immediately after "capture this as a change" is friction, and the surrounding text ("seamlessly", plus L14's own "For a new change, scaffold it first as described below") already leaned that way. The check that settled it was #1715's actual fact pattern — an agent treating answers to its own clarifying questions as consent. An explicit capture request isn't that, so Option 1 doesn't reopen what #1716 closed. The wording that blocks the original report is untouched and now pinned by a test.

One thing your write-up surfaced that I hadn't expected to matter: the carve-out needs a second discriminator. A "yes" to an offer the agent made looks identical to a user-initiated capture request at the point where the decision gets made. So the strict rule still governs when the agent is the one proposing the capture, and that has to be stated in the capture branch itself, not only in the guardrail.

Sorry for not replying before opening #1832 — you offered to do it and deserved the chance. You're credited in the PR. If you'd like to take the follow-ups, #1836 is the same bug class in /opsx:update and is a genuinely one-word fix, and #1833 is the docs side of this one.

[choi138]

No apology needed — #1832 says it better than my write-up did, and the second discriminator you found is the part I had wrong. I was treating "the request is the user's" as self-evident at decision time; it isn't. A "yes" to your own offer and a user-initiated capture request are indistinguishable at the point the gate fires, so the offer has to name the change and the artifacts up front or there is nothing for the confirmation to scope to. Putting that in the capture branch rather than only in the guardrail is what makes it reachable — an agent that lands in the capture branch may never read the guardrail list in that turn.

Checked the diff: the carve-out is stated in all three places it can be read from (the IMPORTANT preamble, the capture transition, and Don't auto-capture), and all three delivery surfaces plus the committed skill carry the same wording, so there's no surface where the old ambiguity survives. LGTM.

Happy to take #1836. It's the same failure mode one layer over: update-change's step 5 confirmation guarantee is unenforceable if step 4's "Apply the requested edit" governs, and since step 5 is itself titled "Confirm and apply", "apply" reads as a write verb in that document. Draft in step 4 at :61 and :152, plus a regression test pinning the ordering. #1833 after that if nobody else has picked it up.

One more in the same class, already fixed and waiting on review: #1829 for #1827. Bulk archive's guardrail declares If archive target exists, fail that change but continue with others and both output templates list Archive directory already exists as an expected outcome, but step 8c mvs with no existence check — so on a target collision POSIX mv nests the change inside the existing archive entry, exits 0, and the agent reports it archived. Same shape as #1828 and #1836: a guarantee stated in the guardrails that the steps never implement. The single-change workflow already has the check; the PR ports its wording to the bulk path and tests both surfaces. CodeRabbit is clean on it. If you'd rather I fold it into whatever you do for #1836 as one "guardrails vs. steps" pass, say so and I'll close #1829 and redo it that way.

[choi138]

Correction to my last comment: disregard the part where I offered to take #1836 and #1833. Both were already yours — #1838 fifteen minutes before that comment, #1840 fifteen minutes after it. I read the issues' state but not their cross-references, so I claimed work that was already done. I've closed my duplicate (#1842) in favor of #1840, which is the better patch anyway — it puts the draft in the conversation and amends step 5 to own the step-4 edit, where mine only changed the verb.

No need to hold follow-ups for me. You're faster at fixing these than I am at claiming them, and from your side there's no way to know whether a "happy to take it" turns into a PR in an hour or never — waiting on that is the worse trade for the project. Ship them.

What I can do that doesn't race you: keep sweeping for this shape. #1827 came out of the same pass as #1828, and #1837 tells me you're already on ff-change and onboard, so I'll stay off those. If a sweep turns up something in an area you haven't opened yet, I'll file the analysis as an issue and leave the fix to you unless you say otherwise — that seems to be the division where I'm actually adding something.

#1829 is the one thing still genuinely waiting: filed before any of this, fix pushed, no human review yet. Whenever it fits.