RFC: Optional deep clarification with topic TODOs, explicit closure, and revision of affected decisions

[wblxr408]

Summary

Could OpenSpec offer an optional deep clarification mode for users who want to work through a complex idea topic by topic, keep exploring the important branches within each topic, explicitly decide when to move on, and revisit earlier conclusions when later decisions change their premises?

The proposed behavior combines a visible clarification TODO, a live map of decision dependencies, evidence-based follow-up questions, explicit topic closure, and targeted review after a decision changes. I am opening this as a design discussion first, following CONTRIBUTING.md. The records below are candidate interaction examples, not a proposed mandatory file format or an implementation commitment.

1. Problem and intended use

In a substantial planning conversation, one answer often reveals several more decisions. A plausible solution may still hide an assumption about data, offline behavior, failure handling, migration, or acceptance criteria. An assistant can move on too quickly, while the user still expects to explore the current issue.

The opposite problem also matters: an assistant can keep asking questions without explaining what remains unresolved, repeat facts already available in the repository, or make an interview feel endless.

Later answers introduce another difficulty. If a user revises an earlier requirement, a checklist can continue showing dependent topics as complete even though their conclusions relied on the old requirement. The conversation may look finished while the resulting plan contains incompatible decisions.

This would help users exploring complex features, architecture choices, or initially vague product ideas, across supported agents and models. Users should explicitly choose this depth of interaction and retain control over pausing, deferring, changing order, and ending it.

2. Relationship to existing work

Related work	What it already considers	What I would like to discuss further
Original #1017 design	A live decision tree, proactive branch exploration, dependency ordering, grounded recommendations, and revisiting downstream assumptions.	Build on that depth with explicit topic closure, conflict records, and a review lifecycle for affected conclusions.
Merged #1017	Focused discovery while preserving user flexibility. Its description explains why exhaustive interviewing and a mandatory recommendation format were narrowed.	Make deeper exploration an explicit user choice and define observable stopping and continuation rules.
#702	Ambiguity categories, prioritized questions, incremental integration, and coverage reporting; its proposed sessions cap questions at five.	Use coverage categories while allowing a topic to require multiple rounds and newly discovered branches.
#893 and #783	Artifact consistency, prioritized issues, working decisions, and review one issue at a time using a scratchpad.	Also cover discovery before artifacts exist, and define how confirmation, conflicts, and later changes affect topic state.

These ideas have substantial prior art. The proposed addition is a clearer interaction contract for depth, closure, and revision, rather than a claim that question trees or decision tracking are new.

3. Start with evidence and a dynamic topic agenda

Before asking factual questions, inspect relevant existing specs, changes, source, tests, documentation, and project guidance. Separate user-stated requirements, observed project facts, accepted decisions, agent recommendations, and unverified assumptions.

Generate a visible agenda of decisions that materially affect the user's goal. Each topic has a stable identifier, purpose, status, dependencies, and a concise account of progress or blockers. Reordering topics preserves their identifiers. Topics may be split or merged with their history and references retained.

Resolve prerequisites before dependent details where practical. Dependencies may be conditional: choosing A can activate one branch and make another irrelevant. Mutually dependent decisions may need to be explored together; the assistant should explain and propose that grouping instead of creating a circular wait.

New discoveries can add topics. If a discovery expands the agreed scope, present the expansion as a choice before treating it as required work. Reuse answers already supplied, including when the user answers several topics in one message.

4. Deep questioning within a topic

One topic is a decision area, not a single question. For example, an offline-use topic may require several rounds on available operations, local changes, reconnection, and recovery.

After each answer, examine whether it is concrete enough, what assumptions it depends on, what new branches it opens, what important boundaries remain, and whether it affects another decision. Ask the next focused question with the greatest relevance to the current unresolved decision. If the user asks for a batch, group related questions without losing their individual dispositions.

Keep exploring relevant major branches until each has an explicit disposition: decided, deferred, blocked, or inapplicable with a reason. Selecting the first plausible approach should trigger examination of its material assumptions, failure cases, and tradeoffs before closure is proposed.

Here, thoroughness means accounting for important branches within the declared scope. The assistant cannot guarantee discovery of every unknown. It should explain remaining uncertainty and the basis for considering a topic ready for confirmation. Question count is not evidence of coverage. A user-selected time or question budget can bound a session, with unfinished work retained accurately.

5. Coverage and question quality

Use an applicability review to discover omissions. The categories below draw on the prior clarification proposal; they are not a requirement to ask ten sets of questions for every change.

Dimension	Examples of what to examine
Outcome and scope	User value, success conditions, priorities, non-goals.
Behavior and flows	Actors, triggers, inputs, outputs, transitions, permissions.
Domain and data	Definitions, relationships, validation, ownership, lifecycle.
Interaction	Loading, empty, success, error, interruption, and recovery states.
External dependencies	Contracts, availability, limits, failures, retries, fallbacks.
Boundaries and failures	Invalid input, concurrency, duplication, partial success, cancellation.
Quality and constraints	Applicable performance, privacy, security, accessibility, cost, and resource constraints.
Compatibility and migration	Existing behavior, data conversion, rollout, reversal where relevant.
Terminology and consistency	Overloaded terms, conflicting meanings, implicit assumptions.
Acceptance and open matters	Observable completion criteria, evidence gaps, unresolved decisions.

For applicable dimensions, record coverage or remaining gaps. Mark irrelevant branches inapplicable with a concise reason. Make downstream details conditional on the upstream choice instead of interrogating the user about paths they have already ruled out.

A useful question states the decision, why it matters now, what evidence has already been checked, and what it unlocks. Give a recommendation when there is evidence to support one; explain its basis, meaningful alternatives, and tradeoffs. When evidence is insufficient, investigate or state a conditional recommendation rather than inventing certainty.

If the user says they do not know, help with concrete scenarios, examples, comparisons, or an explicitly provisional assumption. Record the assumption as provisional. Avoid treating a suggested default as accepted merely because it was displayed or the user remained silent. Use the host agent's supported interaction tools when appropriate, with an equivalent plain-text path.

6. Candidate clarification TODO format

The overview should be compact, with detail available for the active topic. Clarification progress remains separate from implementation task counts. In particular, deferred, blocked, and inapplicable entries must not silently become completed implementation checkboxes.

Clarification agenda
Scope: ...
Active topic: T01
Progress: 1 confirmed; 1 discussing; 2 pending

| ID | Topic | Status | Depends on | Progress / blocker |
| --- | --- | --- | --- | --- |
| T01 | Offline boundaries | Discussing | None | Working through local edits and reconnection |
| T02 | Storage and synchronization | Pending | T01 | Waiting for the offline boundary |
| T03 | Recovery and conflict handling | Pending | T01, T02 | ... |
| T04 | Data upload and privacy | Confirmed | None | Decision D04 v1 |

For an individual topic:

### T01: Offline boundaries

Status: Discussing
Purpose: Decide which operations must work without a network.
Why it matters: Determines processing location and synchronization behavior.
Depends on: ...
Potentially affects: T02, T03
Current accepted decision: None

#### Evidence and assumptions
- User-stated requirements: ...
- Observed project facts and sources: ...
- Existing accepted decisions: ...
- Agent recommendations: ...
- Assumptions needing validation: ...

#### Branches
| ID | Decision needed | Disposition | Conclusion / open matter |
| --- | --- | --- | --- |
| T01.1 | Operations available offline | Decided | ... |
| T01.2 | Saving local edits | Discussing | ... |
| T01.3 | Reconnection behavior | Pending | Depends on T01.2 |
| T01.4 | Multiple devices | Deferred | Current scope is single-device |

#### Current question
- Decision to make: ...
- Why now: ...
- Evidence already checked: ...
- Recommendation and rationale, if supported: ...
- Alternatives and consequences: ...
- Decisions this unlocks or affects: ...

#### Latest answer and follow-up
- User's answer and source: ...
- Agent's interpretation: ...
- New necessary branches: ...
- Changes to dependencies or assumptions: ...
- Known conflicts: ...

#### Candidate topic conclusion
- Decision and scope: ...
- Preconditions and assumptions: ...
- Tradeoffs and alternatives considered: ...
- Applicable coverage reviewed: ...
- Deferred / blocked items and consequences: ...
- Conflict resolution: ...

#### User confirmation
- Status: Awaiting confirmation
- Exact conclusion / decision version presented: ...
- User's confirmation or requested revision: ...
- Agreement to move on: ...

This is a candidate record structure, not a script to print in full on every turn. Routine updates should show the active question and meaningful changes, while retaining enough detail for review and resumption. A branch can be decided while its parent topic still awaits user confirmation.

7. Topic state and explicit closure

Topic state	Meaning	Expected next action
Pending	Identified but not yet explored.	Select according to scope and dependencies.
Discussing	Evidence gathering, follow-up questions, or comparison is ongoing.	Resolve the next relevant branch.
Awaiting confirmation	A sufficiently developed conclusion has been presented.	Accept user confirmation or revise it.
Confirmed	The user accepted an identified decision version under stated conditions.	Use it as a premise, subject to later review.
Needs review	Changed evidence or premises may affect an accepted conclusion.	Assess the affected branches.
Deferred	The user deliberately postponed the decision.	Retain uncertainty and downstream consequences.
Blocked	Necessary evidence or a prerequisite is missing.	Identify what would unblock it.

Track conflicts separately so an open conflict is not hidden by a topic's single status label. Topic status, branch disposition, and the history of decision versions represent different information.

Before proposing closure, the assistant should establish that the topic's purpose is answered, important applicable branches have dispositions, known blocking contradictions have been handled, and the candidate conclusion states its scope, assumptions, tradeoffs, remaining uncertainty, and consequences of deferrals.

Then the user explicitly accepts the conclusion and agrees to move on. A single response such as 'Accept option B with the stated limit; next topic' can do both. Confirmation refers to the version actually presented. If its substance changes, present the changed conclusion for confirmation again.

Answering a factual question alone does not close the topic. An ambiguous 'yes' should be interpreted using the immediately preceding question; if it could materially refer to different proposals, clarify what was accepted.

The user can request more depth, return to an earlier topic, switch order, or leave the mode. If they request moving on while significant uncertainty remains, explain the consequences and record the resulting deferral or limited decision accurately. A later topic may be explored conditionally, but the unsettled prerequisite remains visible.

8. Conflict discovery and resolution

Check candidate decisions against the current topic, earlier accepted decisions, relevant project facts, and existing artifacts. Include interactions that were not previously represented by explicit dependency links.

Distinguish wording differences, different applicable contexts, a newly discovered false assumption, a changed user preference, and requirements that cannot simultaneously hold. Investigate factual disagreements where possible. Let the user decide product intent and material tradeoffs.

A conflict record could be:

### C01: Cloud processing versus offline requirement
Status: Open
Earlier decision: D01 v1, confirmed under T01; core processing works offline.
New candidate: T05 proposes a cloud service for core processing.
Conflict: The service requires a network for an operation covered by D01 v1.
Evidence / missing facts: ...
Possible reconciliations and consequences: ...
User's resolution: Pending
Accepted replacement decision, if any: ...
Topics to review after resolution: ...

Keep the proposed revision distinct from the previously accepted decision until the user resolves the tradeoff. If new evidence already shows the old conclusion cannot be relied upon, flag it immediately as needing review. Preserve the historical decision while making its current validity clear.

Possible resolutions include retaining the earlier requirement, changing it, narrowing the new proposal, splitting contexts, conducting a targeted investigation, or explicitly deferring the choice. After resolution, record the accepted change and its reason, and assess its consequences before treating dependent conclusions as settled.

9. Decision versions and reopening affected topics

A confirmed decision remains valid under its stated premises. Record the premises and dependencies that matter, at a level proportional to the change.

After an accepted decision is revised, identify direct dependents, follow indirect dependencies, and inspect relevant semantic interactions. Mark potentially affected confirmed topics as Needs review with the specific changed premise. Review can itself reveal more dependencies; follow those until the identified impact has a disposition.

For each affected topic, determine whether its conclusion still holds, whether only an explanation needs adjustment, whether new evidence is required, or whether the user must make another choice. Preserve unaffected conclusions with a brief reason. Reopen only the branches requiring renewed discussion. Materially changed conclusions return to user confirmation with a new decision version.

Keep stable topic IDs and retain old decision versions with their replacement relationships and reasons. A conceptual review record is:

### Review of T02
Trigger: D01 changed from v1 to v2.
Old premise: All core processing is local.
New premise: Selected core operations may use a cloud service.
Affected branches: T02.2, T02.3.
Still-valid branches and reasons: T02.1, ...
Indirect impact: T03 depends on the recovery outcome in T02.3.
Evidence to refresh: ...
Review result: ...
New user decision needed: ...
Updated accepted version / confirmation: ...

A tentative alternative discussed for comparison should not automatically replace an accepted decision or invalidate the entire agenda. Conversely, accepting a new upstream decision should not leave earlier dependent checkmarks silently current.

10. Worked example

Suppose T01 confirms D01 v1: core processing must work offline. T02 confirms a local processing and storage workflow based on D01. T03 confirms recovery behavior based on that workflow. T04 confirms D04 v1: raw user data remains on-device.

During T05, the user proposes a cloud service that uploads raw data for core processing. Before confirming T05, the assistant identifies the conflicts with D01 and D04 and investigates the service facts needed to assess them. It presents choices such as retaining local processing, restricting the cloud service to an optional online capability with an explicit data boundary, or revising the earlier requirements.

If the user chooses to revise those requirements, the assistant records the replacement decisions, reviews the affected branches in T02, and follows their consequences into T03. It reopens the privacy branches affected in T04. An unrelated confirmed accessibility choice remains valid unless an actual interaction is identified.

The user should see why each topic reopens, what remains usable, and what choice is now needed. Changing the text of T01 alone is not sufficient reconciliation.

11. Updates, interruption, and handoff to artifacts

After each answer, integrate it into the relevant topic, identify follow-up branches, update dependencies and known conflicts, and choose the next action: investigate, ask, reconcile, present a conclusion, or move on after user agreement. Show a concise account of material changes.

For long sessions, retain the current topic and question, accepted decision versions, unresolved branches, conditional assumptions, conflicts, and pending impact reviews. On resumption, reconcile the record with current user instructions and available project evidence. If the record is incomplete, identify the missing information instead of inventing previous confirmation.

Conversation records and saved artifacts should follow the existing user's authorization and OpenSpec capture rules. Persisting a clarification record, creating planning artifacts, and starting implementation have distinct purposes. Accepting a topic conclusion should have a clear, limited meaning in the interaction.

When the user requests artifact creation or revision, carry accepted decisions and explicitly retained uncertainty into the appropriate artifacts using the applicable schema. Do not hardcode default artifact names as the only supported layout. Changes affecting existing artifacts should be reconciled in both directions, consistent with the current update workflow. Preserve links from significant decisions to affected requirements or designs where useful.

Clarification can be recommended as ready to conclude when the decisions required for the current scope are confirmed, known blocking conflicts and impact reviews have dispositions, and deferred or blocked items have explicit consequences. The user decides whether to finish exploration and proceed. Pausing with unresolved work is also a valid outcome; report that outcome accurately.

12. Behavior scenarios for evaluating the design

Situation	Expected observable behavior
The initial request is vague.	Build a small relevant agenda, investigate available facts, and ask the next decision that changes the plan.
The user answers 'support offline use.'	Explore the material operations, storage, reconnection, and failure branches that remain unresolved.
An answer opens a necessary subdecision.	Add it to the active topic and continue that branch rather than prematurely closing the parent.
A proposed branch is irrelevant to the accepted scope.	Record why it is inapplicable and avoid unnecessary questioning.
The user selects the first feasible option.	Examine material assumptions and consequences before proposing closure.
The user answers only the current question.	Integrate the answer without treating the entire topic as confirmed.
The user accepts the summarized conclusion and says next.	Confirm that version and advance without a redundant confirmation exchange.
The user says they do not know.	Help with evidence, examples, or an explicitly provisional assumption.
The user gives several answers at once.	Integrate each answer under the appropriate topic and check interactions.
The user deliberately defers or stops.	Retain unresolved status and consequences; respect their requested stopping point.
A later candidate contradicts an accepted decision.	Present the conflict and reconciliation choices before accepting a replacement.
New evidence disproves a premise.	Flag the affected conclusion as needing review, even before a replacement is chosen.
An upstream decision changes.	Review direct and indirect dependents and expose which branches need another user decision.
Some dependent conclusions remain valid.	Preserve them with a reason instead of restarting the entire interview.
Decisions depend on each other.	Explain the cycle and propose joint exploration.
The session is resumed with incomplete records.	State the uncertainty and recover only the missing context.
Formal artifact validation passes.	Treat it as supplementary evidence, not proof that semantic conflicts or user confirmation requirements are satisfied.

These are proposed conversation-level evaluation scenarios. Template tests can establish generated instruction contracts; actual agent behavior and usability need evaluation with representative conversations and models. I have not implemented or empirically validated this design.

13. Possible scope and questions for maintainers

A first step could agree on the opt-in interaction guidance and a lightweight conversational record. Persistence, schema integration, a new workflow command, and any CLI-enforced state would need separate design decisions. The candidate records above are deliberately detailed to make the semantics reviewable; a shipped interface could display far less at any one time.

I would appreciate feedback on:

1. Does an opt-in mode inside Explore fit OpenSpec's philosophy, or should this build on the refinement work in feat: add /opsx:refine command with scratchpad-based artifact review #893 or a community workflow?
2. Which parts of fix(explore): guide planning with focused discovery questions #1017's original deep exploration design are worth retaining, and what boundaries would address the concerns that led to its narrower merged guidance?
3. Is explicit topic-level closure useful, provided users can defer, switch, or stop without repeating approvals for individual factual answers?
4. Is the proposed TODO structure sufficiently precise to track branches, premises, conflicts, and revisions while staying lightweight in ordinary conversation?
5. What is the smallest useful mechanism for detecting affected topics and preserving the validity of earlier decisions?
6. Which conversation examples would best distinguish helpful depth from repetitive or endless questioning?

Prepared with OpenAI Codex from my requirements and iterative review. This is a proposal for discussion before implementation.