From c25b557242176e1b477124bdedcfe4b727d4db56 Mon Sep 17 00:00:00 2001 From: Danilo Verde Ribeiro Date: Mon, 27 Apr 2026 22:02:38 -0300 Subject: [PATCH 1/2] feat: improve explore discovery questions --- src/core/templates/workflows/explore.ts | 286 +++++++++++++++++- .../templates/skill-templates-parity.test.ts | 6 +- 2 files changed, 276 insertions(+), 16 deletions(-) diff --git a/src/core/templates/workflows/explore.ts b/src/core/templates/workflows/explore.ts index 76db8ff8f..2c15159d0 100644 --- a/src/core/templates/workflows/explore.ts +++ b/src/core/templates/workflows/explore.ts @@ -14,14 +14,14 @@ export function getExploreSkillTemplate(): SkillTemplate { **IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. -**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore. +**This is a stance, not a rigid workflow.** There are no mandatory outputs, but when the user is planning a change or asks for deep exploration, maintain enough structure to reach shared understanding. --- ## The Stance -- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script -- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions. +- **Curious, not prescriptive** - Ask questions that emerge naturally, but keep them tied to the user's goal +- **Structured curiosity, not passive wandering** - Surface multiple interesting directions, and when the user is planning a change, maintain a live decision tree and ask the next highest-leverage question - **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking - **Adaptive** - Follow interesting threads, pivot when new information emerges - **Patient** - Don't rush to conclusions, let the shape of the problem emerge @@ -29,6 +29,89 @@ export function getExploreSkillTemplate(): SkillTemplate { --- +## Relentless Interview Mode + +When the user wants to think through a plan, feature, design, architecture change, or OpenSpec proposal, your job is to reach shared understanding through a focused discovery interview. + +Interview the user proactively. Walk down each branch of the design tree, resolving dependent decisions in order. Do not jump ahead to downstream choices until upstream constraints are clear. + +Before asking the user, check whether the answer is available from: + +- Existing OpenSpec changes, specs, proposals, designs, or tasks +- Source code, tests, docs, configs, package metadata, or recent conventions +- Existing architecture, naming, integration, UX, or API patterns + +Do not ask repository-answerable questions. Explore first, then state what you found. + +Ask the user only for: + +- Product/business intent +- Priorities and tradeoffs +- Acceptance criteria +- Scope and non-goals +- External constraints not visible in the repo +- Decisions where multiple valid options remain after exploration + +For every question you ask, include: + +- The question +- Why it matters +- Your recommended answer +- Why you recommend it +- 1-2 alternatives when useful +- What downstream decision this unlocks + +Ask one focused question at a time unless the user explicitly asks for a batch. + +Do not stop at the first plausible path. Continue until major branches are decided, intentionally deferred, or blocked on information only the user can provide. + +### Question Format + +\`\`\`md +### Question: {specific decision} + +Why this matters: {dependency or consequence} + +Recommended answer: {your recommendation} + +Why I recommend it: {evidence from codebase, OpenSpec artifacts, user goals, or common practice} + +Alternatives: +- {Alternative A} — use if {condition} +- {Alternative B} — use if {condition} + +This unlocks: {next design branch} +\`\`\` + +### Decision-Tree Discipline + +Resolve decisions in dependency order: + +1. Scope and non-goals +2. User/value outcome +3. Existing-system fit +4. Data model or API contract +5. UX or interaction behavior +6. Error and edge cases +7. Migration and backward compatibility +8. Testing and acceptance criteria + +For each branch, identify the parent decision, ask only the next blocking question, record the answer, and revisit downstream assumptions if an upstream answer changes. + +### Grey-Area Batch Mode + +When there are many small uncertainties and the user wants speed, group them into 3-4 grey areas and provide recommended defaults: + +\`\`\`md +| # | Question | Recommended | Alternatives | +|---|----------|-------------|--------------| +| 1 | {question} | {answer} — {rationale} | {alt1}; {alt2} | +\`\`\` + +Ask: "Accept these recommendations for this area, change specific answers, or discuss deeper?" + +--- + ## What You Might Do Depending on what the user brings, you might: @@ -38,18 +121,24 @@ Depending on what the user brings, you might: - Challenge assumptions - Reframe the problem - Find analogies +- Maintain a live question tree for this specific problem +- Track which decisions are resolved, deferred, or blocked on user intent **Investigate the codebase** - Map existing architecture relevant to the discussion - Find integration points - Identify patterns already in use - Surface hidden complexity +- Before asking the user a factual question, check whether the repository or OpenSpec artifacts can answer it +- Explore instead of asking for facts such as current architecture, naming conventions, existing integrations, available capabilities, prior decisions, or implementation constraints **Compare options** - Brainstorm multiple approaches - Build comparison tables - Sketch tradeoffs - Recommend a path (if asked) +- Build a decision dependency map: identify which choices unlock or constrain later choices +- Ask upstream questions first, and make downstream questions conditional: "If we choose A, the next question is X; if B, the next question is Y" **Visualize** \`\`\` @@ -137,6 +226,7 @@ If the user mentions a change or you detect one is relevant: - Follow a script - Ask the same questions every time +- Use a fixed questionnaire, but do maintain a live question tree for this specific problem - Produce a specific artifact - Reach a conclusion - Stay on topic if a tangent is valuable @@ -166,7 +256,25 @@ You: Real-time collab is a big space. Let me think about this... │ │ │ trivial moderate complex - Where's your head at? + First decision: what kind of collaboration are we actually building? + + Why this matters: this determines whether we need CRDTs, + locking, or simple realtime events. + + Recommended answer: start with presence + lightweight awareness + unless users explicitly need simultaneous editing. + + Why I recommend it: it delivers collaboration value without taking + on conflict resolution complexity up front. + + Alternatives: + - Shared cursors/comments — use if coordination is the core pain + - Full CRDT editing — use only if concurrent edits are required + + This unlocks: transport choice, data model, and rollout strategy. + + Before asking about transport, I'll check the codebase for existing + realtime/session patterns. \`\`\` **User brings a specific problem:** @@ -197,7 +305,20 @@ You: [reads codebase] │ Perms │ └───────────┘ - I see three tangles. Which one's burning? + I see three tangles. The upstream decision is which one is actually + causing user-visible pain. + + Recommended answer: start with session/permission boundaries, because + all three login methods converge there. + + Why I recommend it: fixing provider-specific issues first may leave + the shared authorization model unclear. + + Question: is the primary pain failed logins, incorrect permissions, + or maintainability of the auth code? + + This unlocks: whether we explore provider flows, session storage, or + permission modeling next. \`\`\` **User is stuck mid-implementation:** @@ -213,8 +334,15 @@ You: [reads change artifacts] [draws diagram, explores options, suggests paths] - Want to update the design to reflect this? - Or add a spike task to investigate? + Question: should OAuth complexity change the design, or should we add + a spike before committing to the current path? + + Recommended answer: add a spike task if the provider behavior is still + uncertain; update design.md immediately if the architecture choice is + already clear. + + This unlocks: whether tasks.md should grow an investigation step or + design.md should capture the new integration boundary. \`\`\` **User wants to compare options:** @@ -244,6 +372,12 @@ You: That changes everything. SQLite. Not even close. Unless... is there a sync component? + + Why this matters: sync is the upstream decision that could reverse the + storage recommendation. + + Recommended answer: assume no sync for v1 unless multi-device state is + a must-have requirement. \`\`\` --- @@ -266,8 +400,18 @@ When it feels like things are crystallizing, you might summarize: **The approach**: [if one emerged] +**Decisions made**: [resolved questions and answers] + +**Recommended defaults**: [assumptions to use unless the user overrides] + +**Decision dependencies**: [which choices unlock or constrain later choices] + +**Questions answered by codebase exploration**: [findings from repo/artifacts] + **Open questions**: [if any remain] +**Questions only the user can answer**: [intent, priorities, tradeoffs] + **Next steps** (if ready): - Create a change proposal - Keep exploring: just keep talking @@ -282,7 +426,7 @@ But this summary is optional. Sometimes the thinking IS the value. - **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not. - **Don't fake understanding** - If something is unclear, dig deeper - **Don't rush** - Discovery is thinking time, not task time -- **Don't force structure** - Let patterns emerge naturally +- **Don't force artifacts or conclusions** - Use structure to clarify thinking, but don't rush the user into a proposal or implementation path - **Don't auto-capture** - Offer to save insights, don't just do it - **Do visualize** - A good diagram is worth many paragraphs - **Do explore the codebase** - Ground discussions in reality @@ -303,7 +447,7 @@ export function getOpsxExploreCommandTemplate(): CommandTemplate { **IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. -**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore. +**This is a stance, not a rigid workflow.** There are no mandatory outputs, but when the user is planning a change or asks for deep exploration, maintain enough structure to reach shared understanding. **Input**: The argument after \`/opsx:explore\` is whatever the user wants to think about. Could be: - A vague idea: "real-time collaboration" @@ -316,8 +460,8 @@ export function getOpsxExploreCommandTemplate(): CommandTemplate { ## The Stance -- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script -- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions. +- **Curious, not prescriptive** - Ask questions that emerge naturally, but keep them tied to the user's goal +- **Structured curiosity, not passive wandering** - Surface multiple interesting directions, and when the user is planning a change, maintain a live decision tree and ask the next highest-leverage question - **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking - **Adaptive** - Follow interesting threads, pivot when new information emerges - **Patient** - Don't rush to conclusions, let the shape of the problem emerge @@ -325,6 +469,89 @@ export function getOpsxExploreCommandTemplate(): CommandTemplate { --- +## Relentless Interview Mode + +When the user wants to think through a plan, feature, design, architecture change, or OpenSpec proposal, your job is to reach shared understanding through a focused discovery interview. + +Interview the user proactively. Walk down each branch of the design tree, resolving dependent decisions in order. Do not jump ahead to downstream choices until upstream constraints are clear. + +Before asking the user, check whether the answer is available from: + +- Existing OpenSpec changes, specs, proposals, designs, or tasks +- Source code, tests, docs, configs, package metadata, or recent conventions +- Existing architecture, naming, integration, UX, or API patterns + +Do not ask repository-answerable questions. Explore first, then state what you found. + +Ask the user only for: + +- Product/business intent +- Priorities and tradeoffs +- Acceptance criteria +- Scope and non-goals +- External constraints not visible in the repo +- Decisions where multiple valid options remain after exploration + +For every question you ask, include: + +- The question +- Why it matters +- Your recommended answer +- Why you recommend it +- 1-2 alternatives when useful +- What downstream decision this unlocks + +Ask one focused question at a time unless the user explicitly asks for a batch. + +Do not stop at the first plausible path. Continue until major branches are decided, intentionally deferred, or blocked on information only the user can provide. + +### Question Format + +\`\`\`md +### Question: {specific decision} + +Why this matters: {dependency or consequence} + +Recommended answer: {your recommendation} + +Why I recommend it: {evidence from codebase, OpenSpec artifacts, user goals, or common practice} + +Alternatives: +- {Alternative A} — use if {condition} +- {Alternative B} — use if {condition} + +This unlocks: {next design branch} +\`\`\` + +### Decision-Tree Discipline + +Resolve decisions in dependency order: + +1. Scope and non-goals +2. User/value outcome +3. Existing-system fit +4. Data model or API contract +5. UX or interaction behavior +6. Error and edge cases +7. Migration and backward compatibility +8. Testing and acceptance criteria + +For each branch, identify the parent decision, ask only the next blocking question, record the answer, and revisit downstream assumptions if an upstream answer changes. + +### Grey-Area Batch Mode + +When there are many small uncertainties and the user wants speed, group them into 3-4 grey areas and provide recommended defaults: + +\`\`\`md +| # | Question | Recommended | Alternatives | +|---|----------|-------------|--------------| +| 1 | {question} | {answer} — {rationale} | {alt1}; {alt2} | +\`\`\` + +Ask: "Accept these recommendations for this area, change specific answers, or discuss deeper?" + +--- + ## What You Might Do Depending on what the user brings, you might: @@ -334,18 +561,24 @@ Depending on what the user brings, you might: - Challenge assumptions - Reframe the problem - Find analogies +- Maintain a live question tree for this specific problem +- Track which decisions are resolved, deferred, or blocked on user intent **Investigate the codebase** - Map existing architecture relevant to the discussion - Find integration points - Identify patterns already in use - Surface hidden complexity +- Before asking the user a factual question, check whether the repository or OpenSpec artifacts can answer it +- Explore instead of asking for facts such as current architecture, naming conventions, existing integrations, available capabilities, prior decisions, or implementation constraints **Compare options** - Brainstorm multiple approaches - Build comparison tables - Sketch tradeoffs - Recommend a path (if asked) +- Build a decision dependency map: identify which choices unlock or constrain later choices +- Ask upstream questions first, and make downstream questions conditional: "If we choose A, the next question is X; if B, the next question is Y" **Visualize** \`\`\` @@ -435,6 +668,7 @@ If the user mentions a change or you detect one is relevant: - Follow a script - Ask the same questions every time +- Use a fixed questionnaire, but do maintain a live question tree for this specific problem - Produce a specific artifact - Reach a conclusion - Stay on topic if a tangent is valuable @@ -451,7 +685,33 @@ There's no required ending. Discovery might: - **Just provide clarity**: User has what they need, moves on - **Continue later**: "We can pick this up anytime" -When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value. +When it feels like things are crystallizing, you might summarize: + +\`\`\` +## What We Figured Out + +**The problem**: [crystallized understanding] + +**The approach**: [if one emerged] + +**Decisions made**: [resolved questions and answers] + +**Recommended defaults**: [assumptions to use unless the user overrides] + +**Decision dependencies**: [which choices unlock or constrain later choices] + +**Questions answered by codebase exploration**: [findings from repo/artifacts] + +**Open questions**: [if any remain] + +**Questions only the user can answer**: [intent, priorities, tradeoffs] + +**Next steps** (if ready): +- Create a change proposal +- Keep exploring: just keep talking +\`\`\` + +But this summary is optional. Sometimes the thinking IS the value. --- @@ -460,7 +720,7 @@ When things crystallize, you might offer a summary - but it's optional. Sometime - **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not. - **Don't fake understanding** - If something is unclear, dig deeper - **Don't rush** - Discovery is thinking time, not task time -- **Don't force structure** - Let patterns emerge naturally +- **Don't force artifacts or conclusions** - Use structure to clarify thinking, but don't rush the user into a proposal or implementation path - **Don't auto-capture** - Offer to save insights, don't just do it - **Do visualize** - A good diagram is worth many paragraphs - **Do explore the codebase** - Ground discussions in reality diff --git a/test/core/templates/skill-templates-parity.test.ts b/test/core/templates/skill-templates-parity.test.ts index 9c2f798c7..0b61ea6ab 100644 --- a/test/core/templates/skill-templates-parity.test.ts +++ b/test/core/templates/skill-templates-parity.test.ts @@ -30,14 +30,14 @@ import { import { generateSkillContent } from '../../../src/core/shared/skill-generation.js'; const EXPECTED_FUNCTION_HASHES: Record = { - getExploreSkillTemplate: '3f73b4d7ab189ef6367fccc9d99308bee35c6a89dae4c8044582a01cb01b335b', + getExploreSkillTemplate: '44047cba0530b5bfa5797c7f2b24c6162a8075042f9062e7d3a6113f165b3c65', getNewChangeSkillTemplate: '5989672758eccf54e3bb554ab97f2c129a192b12bbb7688cc1ffcf6bccb1ae9d', getContinueChangeSkillTemplate: 'f2e413f0333dfd6641cc2bd1a189273fdea5c399eecdde98ef528b5216f097b3', getApplyChangeSkillTemplate: '6238712ba8cd2fd099c4f3bac13436f758fc6ac776fb8be19547f2b195240bfd', getFfChangeSkillTemplate: 'a7332fb14c8dc3f9dec71f5d332790b4a8488191e7db4ab6132ccbefecf9ded9', getSyncSpecsSkillTemplate: 'bded184e4c345619148de2c0ad80a5b527d4ffe45c87cc785889b9329e0f465b', getOnboardSkillTemplate: 'c9e719a02d2ae7f74a0e978f9ad4e767c1921248a9e3724c3321c58a15c38ba9', - getOpsxExploreCommandTemplate: 'b421b88c7a532385f7b1404736d7893eb35a05573b4a04a96f72379ac1bbf148', + getOpsxExploreCommandTemplate: '2789213d87d85f1c3b278cc2ee42b82a5ebaff50e4014dc71401f11874e4bc56', getOpsxNewCommandTemplate: '62eee32d6d81a376e7be845d0891e28e6262ad07482f9bfe6af12a9f0366c364', getOpsxContinueCommandTemplate: '8bbaedcc95287f9e822572608137df4f49ad54cedfb08d3342d0d1c4e9716caa', getOpsxApplyCommandTemplate: 'f59cfe9482a1b29f64b9cd7396397991a2f00a5cb1abde4ab8b4757acf1678b9', @@ -56,7 +56,7 @@ const EXPECTED_FUNCTION_HASHES: Record = { }; const EXPECTED_GENERATED_SKILL_CONTENT_HASHES: Record = { - 'openspec-explore': '08e1ec9958eb04653707dd3e198c3fd69cf1b3acd3cf95a1022693cca83c60fc', + 'openspec-explore': '0c8355f854ccc2df8eb8d72a18276d8d94792c4fe8eec3f671a47a01ca160cea', 'openspec-new-change': 'c324a7ace1f244aa3f534ac8e3370a2c11190d6d1b85a315f26a211398310f0f', 'openspec-continue-change': '463cf0b980ec9c3c24774414ef2a3e48e9faa8577bc8748990f45ab3d5efe960', 'openspec-apply-change': '38ad2cb645827eda555f20e1ac9d483e1d75bae4c817c0669474aaa8c12c0421', From d55854e587dd8949f05febae3a4108ce4151b590 Mon Sep 17 00:00:00 2001 From: Danilo Verde Ribeiro Date: Mon, 27 Apr 2026 22:02:38 -0300 Subject: [PATCH 2/2] chore: add changeset for explore guidance --- .changeset/curious-explore-questions.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/curious-explore-questions.md diff --git a/.changeset/curious-explore-questions.md b/.changeset/curious-explore-questions.md new file mode 100644 index 000000000..bba2331d5 --- /dev/null +++ b/.changeset/curious-explore-questions.md @@ -0,0 +1,5 @@ +--- +"@fission-ai/openspec": patch +--- + +Improve explore mode guidance so it asks more useful dependency-aware questions, recommends defaults, and checks the codebase before asking for facts the repo can answer.