diff --git a/plugins/aidd-refine/CATALOG.md b/plugins/aidd-refine/CATALOG.md index 9212c98ac..1b5b399b9 100644 --- a/plugins/aidd-refine/CATALOG.md +++ b/plugins/aidd-refine/CATALOG.md @@ -29,18 +29,13 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-capture.md](skills/01-brainstorm/actions/01-capture.md) | - | -| `actions` | [02-probe.md](skills/01-brainstorm/actions/02-probe.md) | - | -| `actions` | [03-integrate.md](skills/01-brainstorm/actions/03-integrate.md) | - | -| `actions` | [04-finalize.md](skills/01-brainstorm/actions/04-finalize.md) | - | +| `actions` | [02-explore.md](skills/01-brainstorm/actions/02-explore.md) | - | +| `actions` | [03-conclude.md](skills/01-brainstorm/actions/03-conclude.md) | - | | `assets` | [discovery-brief.md](skills/01-brainstorm/assets/discovery-brief.md) | - | -| `references` | [completion-options.md](skills/01-brainstorm/references/completion-options.md) | - | | `references` | [discovery-map.md](skills/01-brainstorm/references/discovery-map.md) | - | -| `references` | [interview-depth.md](skills/01-brainstorm/references/interview-depth.md) | - | | `references` | [persistence.md](skills/01-brainstorm/references/persistence.md) | - | | `references` | [probing.md](skills/01-brainstorm/references/probing.md) | - | -| `references` | [question-angles.md](skills/01-brainstorm/references/question-angles.md) | - | -| `references` | [readiness.md](skills/01-brainstorm/references/readiness.md) | - | -| `-` | [SKILL.md](skills/01-brainstorm/SKILL.md) | `Clarify a vague product or technical intent through natural discovery. Use when the user has a half-formed idea, ambiguous request, or asks to brainstorm, discover, refine, or clarify. Not for artifact gap scans, planning, or code.` | +| `-` | [SKILL.md](skills/01-brainstorm/SKILL.md) | `Clarify a vague idea through questions. Use when the user has a half-formed idea, ambiguous request, or asks to brainstorm, discover, refine, or clarify. Not for artifact gap scans, planning, or code.` | #### `skills/02-challenge` diff --git a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md index e0eb39c62..b76bbc0d2 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md +++ b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md @@ -1,34 +1,29 @@ --- name: 01-brainstorm -description: Clarify a vague product or technical intent through natural discovery. Use when the user has a half-formed idea, ambiguous request, or asks to brainstorm, discover, refine, or clarify. Not for artifact gap scans, planning, or code. +description: Clarify a vague idea through questions. Use when the user has a half-formed idea, ambiguous request, or asks to brainstorm, discover, refine, or clarify. Not for artifact gap scans, planning, or code. argument-hint: idea --- # Brainstorm +## Actions + ```mermaid flowchart LR - capture --> probe --> integrate - integrate -->|"open fork"| probe - integrate -->|"clear enough"| finalize - finalize -->|"user wants more"| probe + capture["capture
actions/01-capture.md"] --> explore["explore
actions/02-explore.md"] + explore -->|"ask questions"| user((user answers)) + user --> explore + explore -->|"clear enough, or user stops"| conclude["conclude
actions/03-conclude.md"] + conclude -->|"correct: revise, show again"| conclude + conclude -->|"explore more"| explore + conclude -->|"approve: offer where to keep it"| persist["persistence
references/persistence.md"] --> done((done)) ``` -## Actions - -Run the flow above. Read only the next action's file before running it. - -| Action | Does | -| ------ | ---- | -| capture | restate the idea and pick what matters next | -| probe | ask the next useful questions | -| integrate | fold answers and decide whether to continue | -| finalize | produce the approved refined idea | +Each box is a file: read it, then do what it says. ## Transversal rules -- Clarify intent, never plan, build, or code. -- Ask only questions that can change what gets built. -- Flag assumptions as assumptions. -- State a leaning and its tradeoff when facts already point one way. -- Hide process words: no density, coverage, nodes, completeness, matrix, or frame unless the user asks for an audit. -- Wait after questions, approval, and persistence choices. +- Clarify only: never plan or code. +- Ask a question only if its answer changes the outcome. +- Talk about the idea, never the skill's steps or files. +- After questions, approval or persistence options, wait. +- When the user wants to stop or asks for a summary, go to conclude and produce the brief in the chat. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/01-capture.md b/plugins/aidd-refine/skills/01-brainstorm/actions/01-capture.md index c004f54a5..ecf4dca2d 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/01-capture.md +++ b/plugins/aidd-refine/skills/01-brainstorm/actions/01-capture.md @@ -1,29 +1,17 @@ # 01 - Capture -Restate the idea and pick what matters next. - -## Goal - -Start from the user's words without turning them into a solution. +Understand the idea. ## Input -The user's idea, however vague, at any level. +The user's idea, however vague. ## Process -1. **Require.** If no idea is present, ask for one and wait. -2. **Restate.** Capture the idea in short bullets, preserving uncertainty. -3. **Scan.** Apply [interview depth](../references/interview-depth.md) and [discovery map](../references/discovery-map.md) silently. -4. **Open.** Hand the highest-impact open point to probe. +1. With no idea, ask for one and stop. +2. Say the idea back briefly, in the user's words, keeping what is still uncertain. +3. Go to explore. ## Output -The idea so far and first open point. - -## Test - -- The first open point is known before probing. -- With no idea, the action asks for one and stops. -- User-facing text does not expose process labels. -- No solution, plan, or code is committed. +The idea said back. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/02-explore.md b/plugins/aidd-refine/skills/01-brainstorm/actions/02-explore.md new file mode 100644 index 000000000..629336c9c --- /dev/null +++ b/plugins/aidd-refine/skills/01-brainstorm/actions/02-explore.md @@ -0,0 +1,26 @@ +# 02 - Explore + +Clarify the idea through questions until it is clear enough to conclude. + +## Input + +The conversation so far. + +## Process + +1. Take stock: what is clear, what is assumed and why, what is open. +2. If no point in the [discovery map](../references/discovery-map.md) could still change the outcome, propose concluding. +3. Otherwise, pick the next point: what the last message opened, or the next one in the map. +4. Ask about it with the [probing techniques](../references/probing.md) that fit. +5. Wait for the answer, then repeat from step 1. + +## Output + +A few focused questions on one point. + +## Rules + +- On a contradiction, ask which one stands. +- When facts converge, state your leaning and its tradeoff. +- Stay at the user's level; leave the how to planning. +- Sound like a conversation, not a form. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/02-probe.md b/plugins/aidd-refine/skills/01-brainstorm/actions/02-probe.md deleted file mode 100644 index eceee1db6..000000000 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/02-probe.md +++ /dev/null @@ -1,28 +0,0 @@ -# 02 - Probe - -Ask the next useful question set. - -## Goal - -Reduce the most important ambiguity without running a checklist. - -## Input - -The idea so far, assumptions, and last answer. - -## Process - -1. **Choose.** Apply [discovery map](../references/discovery-map.md) and pick one live point or dependency chain. -2. **Question.** Use [probing](../references/probing.md) and [question angles](../references/question-angles.md) for one focused set. -3. **Challenge.** Name the fork, assumption, edge case, or failure mode when useful. -4. **Wait.** Ask naturally and stop. - -## Output - -Focused questions, then no further action until the user answers. - -## Test - -- Questions target one live point. -- No already-answered or decorative question is asked. -- User-facing text feels like conversation, not a form. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/03-conclude.md b/plugins/aidd-refine/skills/01-brainstorm/actions/03-conclude.md new file mode 100644 index 000000000..f913dbfaf --- /dev/null +++ b/plugins/aidd-refine/skills/01-brainstorm/actions/03-conclude.md @@ -0,0 +1,24 @@ +# 03 - Conclude + +Produce the approved refined idea. + +## Input + +The conversation so far. + +## Process + +1. Fill the [discovery brief](../assets/discovery-brief.md). +2. Show it and ask to approve, correct, or explore more. +3. On a correction, revise it and show it again. +4. To explore more, go to explore. +5. On approval, offer where to keep it, per [persistence](../references/persistence.md). + +## Output + +The approved brief. + +## Rules + +- Write the brief's bullets as facts about the idea, not as a list of categories. +- Write nothing unless the user chooses it. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/03-integrate.md b/plugins/aidd-refine/skills/01-brainstorm/actions/03-integrate.md deleted file mode 100644 index f6c4e683f..000000000 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/03-integrate.md +++ /dev/null @@ -1,30 +0,0 @@ -# 03 - Integrate - -Fold answers and decide whether to continue. - -## Goal - -Keep the clarified idea current and make the loop decision explicit. - -## Input - -The user's answers, idea so far, and assumptions. - -## Process - -1. **Fold.** Update the idea with the user's answer. If it conflicts with something already settled, confirm which stands before folding. -2. **Lean.** State a leaning and tradeoff when facts converge, even unprompted. -3. **Track.** Move assumptions to settled, open, or deferred. -4. **Check.** Apply [readiness](../references/readiness.md) silently to find any remaining fork. -5. **Decide.** Continue probing when one remains or the user asks for more; otherwise finalize. - -## Output - -The updated idea, assumptions, and next action. - -## Test - -- Every new fact is reflected in the idea or assumptions. -- The continue/finalize decision names the remaining gap, or says none remains. -- User-facing text does not expose process labels unless asked. -- A leaning and tradeoff is stated when facts converge, or none did. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md b/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md deleted file mode 100644 index 25567ad69..000000000 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md +++ /dev/null @@ -1,33 +0,0 @@ -# 04 - Finalize - -Produce the approved refined idea. - -## Goal - -End with a precise, natural intent artifact, not a plan. - -## Input - -The clarified idea, assumptions, and conversation evidence. - -## Process - -1. **Draft.** Fill [discovery brief](../assets/discovery-brief.md). -2. **Check.** Verify silently against [readiness](../references/readiness.md). -3. **Ask.** Apply [completion options](../references/completion-options.md) in one open question. - - Correction revises the brief and asks again. - - More probing returns to `02-probe`. - - Session-only writes nothing. -4. **Persist.** If the user approves and chooses persistence, apply [persistence](../references/persistence.md) only for that destination. -5. **Point.** Name the next move in plain words. Never name a plugin or skill. - -## Output - -The approved refined idea and optional persisted destination. - -## Test - -- Process labels and tables are absent unless the user asks for them. -- Bullets read as facts about the idea, not a categorized field list. -- The user can approve, correct, continue probing, keep it session-only, or persist it. -- Nothing is written without user approval and a destination choice. diff --git a/plugins/aidd-refine/skills/01-brainstorm/assets/discovery-brief.md b/plugins/aidd-refine/skills/01-brainstorm/assets/discovery-brief.md index 3aac8b9e2..e2314f6ae 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/assets/discovery-brief.md +++ b/plugins/aidd-refine/skills/01-brainstorm/assets/discovery-brief.md @@ -2,16 +2,16 @@ # - + -## What Is Clear +## Clear -- +- -## Still Open +## Assumed -- +- -## Next Move +## Open - +- diff --git a/plugins/aidd-refine/skills/01-brainstorm/references/completion-options.md b/plugins/aidd-refine/skills/01-brainstorm/references/completion-options.md deleted file mode 100644 index d27889665..000000000 --- a/plugins/aidd-refine/skills/01-brainstorm/references/completion-options.md +++ /dev/null @@ -1,12 +0,0 @@ -# Completion Options - -Offer user-controlled next steps in natural language. - -- Approve: keep the brief as the current refined intent. -- Correct: edit the brief from the user's corrections. -- Continue: return to probe on the point the user names, or on the strongest remaining fork. -- Session-only: leave the brief in chat and write nothing. -- File: after approval, apply [persistence](persistence.md). -- Ticket: after approval, apply [persistence](persistence.md). - -Do not reduce the ending to file, ticket, or session. The user must be able to keep iterating. diff --git a/plugins/aidd-refine/skills/01-brainstorm/references/discovery-map.md b/plugins/aidd-refine/skills/01-brainstorm/references/discovery-map.md index 425b77306..ba213ca44 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/references/discovery-map.md +++ b/plugins/aidd-refine/skills/01-brainstorm/references/discovery-map.md @@ -1,25 +1,29 @@ # Discovery Map -Use this map internally to decide what matters. Do not print labels, branches, or tables unless the user asks for an audit view. +Use this map to decide what to explore next. -## Core Points +Go down the list and take the first point still unclear. Ask with one of its angles, only when it fits. -| Point | Means | Depends on | -| ----- | ----- | ---------- | -| A | outcome, actor, pain, desired change | - | -| B | trigger, flow, visible behavior | A | -| C | scope, non-goals, smallest useful slice | A, B | -| D | inputs, state, API, permissions, invariants | B, C | -| E | acceptance, metric, observable done signal | A-D | -| F | edge case, dependency, rollout, operational risk | C-E | +In the first round, a vague idea (a topic or a solution only) starts at the first point with one example. A precise one (most points there) starts at its single riskiest gap. -## Transversal Branches +## Points -Open one only when it can change a core point. +| Means | Angle | +| ----- | ----- | +| actor, pain, desired change | who benefits, what changes, why now? | +| trigger, steps, visible behavior | one case that should work, one that should not | +| non-goals, smallest useful slice | the smallest useful version, where this stops | +| inputs, state, API, permissions, invariants | dependency, platform, cost, latency, security, ownership | +| acceptance, metric, observable done signal | what proves it works, what fails the idea? | +| edge case, dependency, rollout, operational risk | empty, duplicate, concurrent, stale, missing, hostile, partial | + +## Beyond the list + +Open one only when it can change a point above. | Branch | Use for | | ------ | ------- | -| T | technical or operational tradeoff | -| CB | codebase boundary or ownership | -| TS | type, schema, service, or data contract | -| CP | change path, compatibility, migration, or rollout | +| Tradeoff | technical or operational tradeoff | +| Codebase boundary | codebase boundary or ownership | +| Data contract | type, schema, service, or data contract | +| Change path | change path, compatibility, migration, or rollout | diff --git a/plugins/aidd-refine/skills/01-brainstorm/references/interview-depth.md b/plugins/aidd-refine/skills/01-brainstorm/references/interview-depth.md deleted file mode 100644 index 84d3f829f..000000000 --- a/plugins/aidd-refine/skills/01-brainstorm/references/interview-depth.md +++ /dev/null @@ -1,9 +0,0 @@ -# Interview Depth - -Use input depth internally to choose how much to ask. Do not name the depth to the user. - -- `thin`: topic or solution only. Ask outcome and one concrete example. -- `medium`: actor, behavior, or constraint exists. Ask the next missing dependency. -- `dense`: most points exist. Ask only the highest-risk gap or finalize. - -Prefer fewer questions. A dense input usually needs one sharp fork, not a recap of the method. diff --git a/plugins/aidd-refine/skills/01-brainstorm/references/persistence.md b/plugins/aidd-refine/skills/01-brainstorm/references/persistence.md index e5d45a881..87dbbf342 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/references/persistence.md +++ b/plugins/aidd-refine/skills/01-brainstorm/references/persistence.md @@ -1,14 +1,9 @@ # Persistence -Persist only after the user approves the brief and chooses a destination. +Where the approved brief can live. -## File - -- Create a new dated task folder by default: `aidd_docs/tasks//_/brainstorm.md`. -- Reuse an existing folder only when it is clearly the same current work. -- When a folder is stale, ambiguous, or already has `brainstorm.md`, ask before updating. -- Offer a new dated brief instead of touching an old file when in doubt. - -## Ticket - -Hand off to the project's ticketing capability when one exists. Do not create or update a ticket silently. +| Destination | Do | +| ----------- | -- | +| Conversation | Keep it in the chat. | +| File | `aidd_docs/tasks//_/brainstorm.md`, with `status: approved`. Ask first if the folder is not clearly this work or already has one. | +| Ticket | Hand it to the project's ticketing tool. | diff --git a/plugins/aidd-refine/skills/01-brainstorm/references/probing.md b/plugins/aidd-refine/skills/01-brainstorm/references/probing.md index a8667e4f0..3fdd0bd3e 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/references/probing.md +++ b/plugins/aidd-refine/skills/01-brainstorm/references/probing.md @@ -1,13 +1,15 @@ # Probing -Probe the live fork, not the whole map. +Techniques to sharpen a question when the live point needs it. -Rules: +| Technique | Use when | Example question | +| --------- | -------- | --- | +| Name the fork | two outcomes are still possible | "Is it X or Y?" | +| Force a choice | a fork is unranked | "If only one could stay, which?" | +| Reach the outcome | the idea is a solution | "What does this get you?" | +| Alternatives | the user holds to one solution | "What else would get the same result?" | +| Hidden assumption | success is taken for granted | "What must be true for this to work?" | +| Limits | limits are unsaid | "What must it never do?" | +| Premortem | a risk matters | "It shipped and failed: why?" | -- Ask at the user's altitude: product, technical, operational, or mixed. Leave finer how-to as a flagged assumption for planning. -- Follow the thread opened by the last answer before switching points. -- Name the fork when two different outcomes are still possible. -- Ask for examples when a word can mean two things. -- Challenge a solution-shaped idea by asking what outcome it serves. -- Use premortem for risk: shipped, failed, why? -- Stop when remaining gaps are explicit assumptions, not hidden ambiguity. +Adapt the example question to the idea. diff --git a/plugins/aidd-refine/skills/01-brainstorm/references/question-angles.md b/plugins/aidd-refine/skills/01-brainstorm/references/question-angles.md deleted file mode 100644 index 347459ae2..000000000 --- a/plugins/aidd-refine/skills/01-brainstorm/references/question-angles.md +++ /dev/null @@ -1,10 +0,0 @@ -# Question Angles - -Use one angle only when it fits the live point. - -- Outcome: who benefits, what changes, why now? -- Example: one case that should work, and one that should not. -- Boundary: smallest useful version, explicit non-goals, where this stops. -- Evidence: what proves it works, what fails the idea? -- Constraint: dependency, platform, cost, latency, security, ownership. -- Failure: empty, duplicate, concurrent, stale, missing, hostile, partial. diff --git a/plugins/aidd-refine/skills/01-brainstorm/references/readiness.md b/plugins/aidd-refine/skills/01-brainstorm/references/readiness.md deleted file mode 100644 index e333d6f2e..000000000 --- a/plugins/aidd-refine/skills/01-brainstorm/references/readiness.md +++ /dev/null @@ -1,9 +0,0 @@ -# Readiness - -Use readiness internally to decide whether to continue or finalize. - -- Track each relevant core point and transversal branch as settled, open, or deferred. -- Add a reason for each deferred item. -- Continue probing while an open item can still change the artifact. -- Finalize when unresolved items are explicit assumptions and the user accepts them. -- Never show status, coverage, matrix, or table unless the user asks for an audit view. diff --git a/scripts/__tests__/architecture-rules.property.test.js b/scripts/__tests__/architecture-rules.property.test.js index ba4ab533e..bd53be248 100644 --- a/scripts/__tests__/architecture-rules.property.test.js +++ b/scripts/__tests__/architecture-rules.property.test.js @@ -214,7 +214,11 @@ function realSkills() { return skills; } -/** The skill's content with every table row citing `name` removed. */ +/** + * The skill's content with every citation of `name` removed: the table rows citing it, and the + * `actions/` path in a fenced block (a mermaid node), which has no row to remove and is + * pointed at a file that does not exist instead. + */ function withoutCitationOf(content, name) { const stem = stemOf(name).toLowerCase(); const noExt = name.replace(/\.md$/, "").toLowerCase(); @@ -230,6 +234,7 @@ function withoutCitationOf(content, name) { .map((cell) => cell.trim().replace(/^`|`$/g, "").toLowerCase()); return !cells.includes(stem) && !cells.includes(noExt) && !cells.includes(name.toLowerCase()); }) + .map((line) => line.replaceAll(`actions/${name}`, "actions/removed.md")) .join("\n"); } @@ -243,14 +248,10 @@ test("every router in the tree cites every action it provides", () => { }); test("removing a real router's citation is caught, for every action in the tree", () => { - // `aidd-dev:10-batch` names its one action as a fenced path rather than a table row, so there - // is no row to remove and nothing to catch. It is the one documented exception. - const FENCED_PATH_SKILL = "plugins/aidd-dev/skills/10-batch/SKILL.md"; const missed = []; let checked = 0; for (const { relPath, content, names } of realSkills()) { - if (relPath === FENCED_PATH_SKILL) continue; for (const name of names) { checked += 1; const violations = checkRouterCoherence(relPath, withoutCitationOf(content, name), names);