opsx:explore does not document decisions made

[ieretzkdosha]

Hi 😄
Using OpenSpec 1.1.1 in Cursor with claude-sonnet-4.5-thinking (model chosen intentionally)

I have created a proposal file.
Then ran opsx:explore in a fresh window. When I was done making decisions and adding more information, it just told me to run opsx:continue and did not write anything to disk.
If I were to run the "continue" command on a fresh context, which I would, it would not know about those decisions and they would be "lost".

I would also note that I was not offered to "apply" the changes during the process.

Is this an issue or am I using the tool incorrectly?

Thanks.

[1code-async]

Task completed.

Comment posted on issue #738. Here's a summary of the analysis:

The issue is a known limitation, not a usage error. The opsx:explore workflow is intentionally designed as an ephemeral conversational tool — it has no automatic mechanism to persist decisions to disk. This is tracked as an open design question in openspec/explorations/explore-workflow-ux.md with four potential approaches under consideration.

The comment covers:

• Root cause — the explore template explicitly avoids auto-capturing, relying on the agent to offer and the user to accept, with no enforcement at session end
• Related issues — /opsx-explore behavior #668 (closest duplicate), Improve explore → change transition guidance in skills #720, [Bug] Explore skill doesn't read project context from config.yaml #696, and Feedback request: architecture decision records support #557 all touch on the same gap
• Workarounds — explicitly asking the agent to write decisions before ending, or requesting a proposal be created
• Potential fix direction — implementing an optional export (Approach B/C) so explore sessions produce a persistent summary file that downstream commands can read

---

View full conversation

Powered by 1Code

[1code-async]

Triage Summary

This is a known limitation, not a bug in usage. The opsx:explore workflow is currently designed to be ephemeral — it's a conversational thinking partner that does not automatically persist decisions to disk.

Root Cause

The explore skill template (src/core/templates/workflows/explore.ts:251-258) explicitly treats endings as optional and conversational:

There's no required ending. Discovery might:

• Flow into a proposal: "Ready to start? I can create a change proposal."
• Result in artifact updates: "Updated design.md with these decisions"
• Just provide clarity: User has what they need, moves on

The template instructs the agent to offer to capture decisions (line 132: "The user decides - Offer and move on. Don't pressure. Don't auto-capture.") but there is no mechanism to ensure those decisions are actually written before the session ends. When the agent tells you to run opsx:continue in a new context, that new context has no access to the prior conversation, so any decisions made verbally are indeed lost.

Where Decisions Can Be Captured

The explore template does define a mapping for where insights should go when a change already exists (src/core/templates/workflows/explore.ts:118-126):

Insight Type	Where to Capture
New requirement	specs/<capability>/spec.md
Design decision	design.md
Scope change	proposal.md
New work identified	tasks.md

But this relies on the agent proactively offering to write to these files, and on the user accepting — which may not happen before the agent suggests moving on.

This Is a Recognized Open Design Question

There is an existing exploration document at openspec/explorations/explore-workflow-ux.md that explicitly tracks this as an unresolved problem. It outlines four potential approaches:

• A (Status Quo): Explorations remain conversational only — user manually carries insights forward
• B (Optional Export): Add a "save exploration" option that writes to openspec/explorations/<name>.md
• C (Exploration as Proposal Seed): Auto-save structured notes that become input to the proposal
• D (Explorations Within Changes): Notes live in changes/<name>/explorations/

Currently Approach A (ephemeral) is what's implemented.

Related Issues

This is closely related to several open issues:

• /opsx-explore behavior #668 — /opsx-explore behavior: Reports the same fundamental gap — explore produces no artifacts and suggests it should be able to create them (feature description, proposal) during the session. Closest to a duplicate.
• Improve explore → change transition guidance in skills #720 — Improve explore -> change transition guidance in skills: Addresses the broken handoff from explore to change creation, where context is not properly carried forward.
• [Bug] Explore skill doesn't read project context from config.yaml #696 — Explore skill doesn't read project context from config.yaml: The flip side — explore doesn't read persistent context either, making it disconnected from project state in both directions.
• Feedback request: architecture decision records support #557 — Feedback request: architecture decision records support: Proposes formal ADR support, which would be one concrete way to persist decisions from explore sessions.

Suggested Workarounds (for now)

1. Explicitly ask the agent to write decisions before ending. Say something like: "Before we wrap up, write the decisions we made to design.md" (or whichever artifact is appropriate).
2. If no change exists yet, ask the agent to create a proposal: "Create a change proposal capturing what we discussed." The explore skill is allowed to create OpenSpec artifacts.
3. Copy the conversation summary — if the agent gives a "What We Figured Out" summary, you can manually paste it into a file before starting a fresh context.

Potential Fix Direction

The most impactful change would likely be Approach B or C from the exploration doc — having opsx:explore produce a persistent summary file (e.g., openspec/explorations/<topic>.md) at the end of a session, which opsx:continue and opsx:propose could then read for context. The key files to modify would be:

• src/core/templates/workflows/explore.ts — Add an "Ending" section that instructs the agent to always offer to save a structured summary before suggesting the user move to another command
• src/core/templates/workflows/continue-change.ts — Add logic to check for and read exploration files as additional context when starting a change