diff --git a/docs/CATALOG.md b/docs/CATALOG.md index ec075fd4..31371ab1 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -59,7 +59,7 @@ Meta-cognition: brainstorm, challenge, condense, blind-spot scan, fact-check. | Skill | Role | Actions | | ------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -| `01-brainstorm` | Clarify and refine a request through iterative questioning | `01-capture-request`, `02-ask-probing-questions`, `03-integrate-answers`, `04-refine-and-validate`, `05-confirm-approval` | +| `01-brainstorm` | Clarify a vague request through a bounded convergence loop of targeted questions | `01-capture`, `02-probe`, `03-integrate`, `04-finalize` | | `02-challenge` | Rethink prior work to verify correctness against a plan | `01-challenge` | | `03-condense` | Toggle terse output mode and report token savings | `01-condense`, `02-stats` | | `04-shadow-areas` | Scan a markdown artifact for blind spots | `01-detect`, `02-render-report`, `03-diff` | diff --git a/plugins/aidd-refine/CATALOG.md b/plugins/aidd-refine/CATALOG.md index 32f3acbe..153d6edd 100644 --- a/plugins/aidd-refine/CATALOG.md +++ b/plugins/aidd-refine/CATALOG.md @@ -36,15 +36,14 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| -| `actions` | [01-capture-request.md](skills/01-brainstorm/actions/01-capture-request.md) | - | -| `actions` | [02-ask-probing-questions.md](skills/01-brainstorm/actions/02-ask-probing-questions.md) | - | -| `actions` | [03-integrate-answers.md](skills/01-brainstorm/actions/03-integrate-answers.md) | - | -| `actions` | [04-refine-and-validate.md](skills/01-brainstorm/actions/04-refine-and-validate.md) | - | -| `actions` | [05-confirm-approval.md](skills/01-brainstorm/actions/05-confirm-approval.md) | - | -| `assets` | [question-templates.md](skills/01-brainstorm/assets/question-templates.md) | - | +| `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) | - | +| `assets` | [question-angles.md](skills/01-brainstorm/assets/question-angles.md) | - | | `-` | [README.md](skills/01-brainstorm/README.md) | - | -| `references` | [ambiguity-detection.md](skills/01-brainstorm/references/ambiguity-detection.md) | - | -| `-` | [SKILL.md](skills/01-brainstorm/SKILL.md) | `Interactive brainstorming session to clarify and refine requests through iterative questioning. Use when user mentions unclear requirements, vague ideas, or needs clarification on features. Do NOT use for clear technical specs, implementation details, or when requirements are already well-defined.` | +| `references` | [probing.md](skills/01-brainstorm/references/probing.md) | - | +| `-` | [SKILL.md](skills/01-brainstorm/SKILL.md) | `Clarify a vague idea through deep back-and-forth questioning until it is precise enough to act on. Works at any level, functional, technical, or mixed. Use when the user surfaces a half-formed idea, a fuzzy feature, a technical question, or an under-specified request, or asks to brainstorm, clarify, or refine before committing. Keeps probing and following each answer's threads until no real ambiguity remains or the user is satisfied. Not for analytically scanning a written artifact for gaps (use aidd-refine:04-shadow-areas), critiquing finished work (use aidd-refine:02-challenge), or any implementation, planning, or code.` | #### `skills/02-challenge` diff --git a/plugins/aidd-refine/README.md b/plugins/aidd-refine/README.md index 09acb2ee..65fd8ef2 100644 --- a/plugins/aidd-refine/README.md +++ b/plugins/aidd-refine/README.md @@ -14,7 +14,7 @@ Five skills that refine inputs and outputs through reflection: clarify vague req | Bracket ID | Skill | Description | | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [5.1] | [brainstorm](skills/01-brainstorm/README.md) | Interactive brainstorming session to clarify and refine requests through iterative questioning. | +| [5.1] | [brainstorm](skills/01-brainstorm/README.md) | Clarify a vague request through a bounded loop of targeted questions over six clarity dimensions, converging until the request is precise or the user is satisfied. | | [5.2] | [challenge](skills/02-challenge/README.md) | Rethink prior work to verify correctness against an agreed plan, classifying findings with a confidence score. | | [5.3] | [condense](skills/03-condense/README.md) | Toggle terse output mode with intensity levels so prose drops fluff while code, errors, and warnings stay verbatim. | | [5.4] | [shadow-areas](skills/04-shadow-areas/README.md) | Analytical scan of a written artifact for blind spots: each gap is classified by category and severity, paired with a direct-question probe. | diff --git a/plugins/aidd-refine/skills/01-brainstorm/README.md b/plugins/aidd-refine/skills/01-brainstorm/README.md index 530fa17a..74d23687 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/README.md +++ b/plugins/aidd-refine/skills/01-brainstorm/README.md @@ -2,54 +2,31 @@ # 01 - Brainstorm -Interactive brainstorming session that clarifies and refines a vague request -through iterative questioning, until no ambiguity remains and the user -explicitly approves the result. +Turns a vague idea into a precise one through a deep, natural conversation, at whatever level the user is thinking, functional or technical. It asks pointed questions, follows the threads each answer opens, and challenges assumptions until the idea is clear enough to act on. It digs, it does not tick boxes. ## When to use -- The user surfaces an unclear requirement, a half-formed idea, or a fuzzy - feature description. -- A request feels under-specified and the next step (plan, code, test) would - rest on assumptions. -- The user explicitly asks to brainstorm, refine, or clarify a request. +- The user surfaces a half-formed idea, a fuzzy feature, a technical question, or an under-specified request. +- An idea would otherwise force the next step (plan, code, test) to rest on assumptions. +- The user asks to brainstorm, clarify, or refine before committing. -## When NOT to use +## When not to use -- The technical spec is already clear and actionable. -- The user only needs implementation details on a settled requirement. -- The request is concrete enough that planning or coding can start directly. +- To scan a written artifact for gaps. Use `aidd-refine:04-shadow-areas`. +- To critique finished work. Use `aidd-refine:02-challenge`. +- The idea is already concrete enough to plan or code. -## How to invoke +## The loop -``` -Use skill aidd-refine:01-brainstorm -``` +`capture` restates the idea and reads its altitude. Then `probe → integrate` repeats: each round asks pointed questions on the live thread, follows the forks the answers open, challenges assumptions, and folds the answers back in. It keeps going until no real ambiguity remains or the user is satisfied. There is no fixed round count, the idea is done when it is clear, not on a timer. `finalize` consolidates the refined idea, flags every open assumption and risk, and offers to persist it to a dated file under `aidd_docs/brainstorm/`, a ticket, or the session only. -The skill walks 5 atomic actions: +## What makes it dig -1. `capture-request` - restate the initial intent as bullet points. -2. `ask-probing-questions` - challenge assumptions with targeted questions. -3. `integrate-answers` - fold the user's answers back into the request. -4. `refine-and-validate` - finalize and scan for residual ambiguity. -5. `confirm-approval` - wait for explicit user sign-off. +- **Follows threads, not topics.** It pulls on the fork an answer opens (filename versus full-text search, for instance), where the depth is, instead of cycling a fixed list. +- **Works at your altitude.** A technical question gets technical probing, a fuzzy feature gets product probing, never one level finer than you opened. +- **Leans when the facts point.** When the answers favor one option it says so with the tradeoff, and keeps the implementation as a flagged assumption for planning. +- **Flags, never fakes.** Whatever stays open is reported as an assumption or risk, never dressed up as settled. -The router loops `02 → 03` until the validator marks the request unambiguous. +## Details -## Outputs - -- A refined, bullet-pointed request the user has explicitly approved. -- No code, no plan, no files. Intent only. - -## Prerequisites - -- A user-supplied request, even if vague. -- Willingness to answer clarifying questions before moving forward. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for -each step, [`references/ambiguity-detection.md`](references/ambiguity-detection.md) -for the ambiguity heuristics, and -[`assets/question-templates.md`](assets/question-templates.md) for the reusable -question categories. +See [`SKILL.md`](SKILL.md) for the contract, [`actions/`](actions/) for the four actions, [`references/probing.md`](references/probing.md) for how to read altitude, follow threads, the tactics, and when to stop, and [`assets/question-angles.md`](assets/question-angles.md) for the topical prompt banks. diff --git a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md index 994506a3..d7d77ef6 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md +++ b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md @@ -1,41 +1,41 @@ --- name: 01-brainstorm -description: Interactive brainstorming session to clarify and refine requests through iterative questioning. Use when user mentions unclear requirements, vague ideas, or needs clarification on features. Do NOT use for clear technical specs, implementation details, or when requirements are already well-defined. +description: Clarify a vague idea through deep back-and-forth questioning until it is precise enough to act on. Works at any level, functional, technical, or mixed. Use when the user surfaces a half-formed idea, a fuzzy feature, a technical question, or an under-specified request, or asks to brainstorm, clarify, or refine before committing. Keeps probing and following each answer's threads until no real ambiguity remains or the user is satisfied. Not for analytically scanning a written artifact for gaps (use aidd-refine:04-shadow-areas), critiquing finished work (use aidd-refine:02-challenge), or any implementation, planning, or code. --- # Brainstorm -Clarifies and refines a feature request through structured iterative questioning until no ambiguity remains. Auto-triggers on prompts indicating uncertainty or need for clarification. +Turns a vague idea into a precise one through a deep, natural conversation. Each round asks pointed questions, follows the threads the answers open, and challenges assumptions, until the idea is clear enough to act on. It digs, it does not tick boxes. -## Available actions +## Actions -| # | Action | Role | Input | -| --- | ------------------- | --------------------------------------------- | ------------------ | -| 01 | `capture-request` | Detail initial request in bullet points | user intent | -| 02 | `ask-probing-questions` | Ask questions to challenge assumptions | captured request | -| 03 | `integrate-answers` | Update request with user responses | answers + request | -| 04 | `refine-and-validate` | Finalize and check for ambiguity | updated request | -| 05 | `confirm-approval` | Wait for user approval | refined request | +| # | Action | Role | Input | +| --- | ----------- | --------------------------------------------------------- | ------------------- | +| 01 | `capture` | Restate the idea and read its altitude | the user's idea | +| 02 | `probe` | Ask pointed questions, follow the open thread, challenge | the idea so far | +| 03 | `integrate` | Fold answers in, judge if real ambiguity remains | answers + the idea | +| 04 | `finalize` | Consolidate, flag open assumptions, offer to persist | the clarified idea | ## Default flow -Sequential skill: `01 → 02 → 03 → 04 → 05`. Loop `02 → 03` until no ambiguity (router checks `03` output for `needs_more`). +`capture` once, then loop `probe → integrate` until no real ambiguity remains or the user is satisfied, then `finalize`. There is no fixed round count, the idea is done when it is clear, not on a timer. Run each action's `## Test` before the next. ## Transversal rules -- Never assume technical solutions upfront. -- Use bullet points for clarity. -- DO NOT IMPLEMENT ANYTHING. -- Wait for user response after questions or approval prompts. +- Clarify the idea, never build it. Surface the leaning and its tradeoff when the facts point one way, but do not lock a solution, write a plan, or produce code. +- Stay tool-agnostic. Refine the idea on its own terms. Never write a `plugin:skill` identifier, name the capability in plain words instead (the project's rule-writing, its planning step), never the skill that provides it. How it gets built is the next step's job, not brainstorm's. +- Work at the user's altitude, functional or technical, and probe at that grain, never one level finer. +- Follow the thread. Pull on what each answer opens, especially a fork where two materially different builds are still possible, rather than cycling fixed topics. Depth over breadth. +- Challenge assumptions and surface limit cases as they appear, do not save them for the end. +- Ask a focused set of pointed questions, several when they share the thread, never a question already answered, never a flat checklist. Keep it a conversation. +- Keep going until the idea is clear or the user stops. Never stop on a count. +- Flag every open assumption, never present a guess as settled. +- Wait for the user after every question and at approval. ## References -- `@references/ambiguity-detection.md`: How to identify and resolve unclear requirements. +- `references/probing.md`: how to read altitude, follow threads, the probing tactics, and when to stop. ## Assets -- `@assets/question-templates.md`: Reusable probing question categories. - -## External data - -- None. \ No newline at end of file +- `assets/question-angles.md`: concrete question prompts to draw from when probing. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/01-capture-request.md b/plugins/aidd-refine/skills/01-brainstorm/actions/01-capture-request.md deleted file mode 100644 index e6a5a4e7..00000000 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/01-capture-request.md +++ /dev/null @@ -1,29 +0,0 @@ -# 01 - Capture Request - -Detail the initial feature request in bullet points (no technical aspects). - -## Inputs - -- `user_intent` : the user's prompt or request text. - -## Outputs - -Bullet-point list of features/requirements. - -```markdown -- Feature 1 -- Feature 2 -``` - -## Depends on - -- None - -## Process - -1. Parse `user_intent` into non-technical bullet points. -2. Output the structured list. - -## Test - -- Output is a list of bullet points without technical details. \ No newline at end of file diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/01-capture.md b/plugins/aidd-refine/skills/01-brainstorm/actions/01-capture.md new file mode 100644 index 00000000..f24a1f8a --- /dev/null +++ b/plugins/aidd-refine/skills/01-brainstorm/actions/01-capture.md @@ -0,0 +1,21 @@ +# 01 - Capture + +Restate the idea in plain bullets and read the level it sits at. + +## Input + +The user's idea, however vague, at any level. + +## Output + +The idea restated as short bullets, plus a read of its altitude, then a handoff to probing. + +## Process + +1. **Restate.** Parse the idea into short, non-technical bullets. Capture what the user means, never commit a solution. +2. **Read the altitude.** Note whether the idea is functional, technical, or mixed, and the grain the user is thinking at. This sets the level to probe at, never finer. See `@../references/probing.md`. +3. **Open.** Hand to `02-probe` to begin the questioning. + +## Test + +- The output restates the idea as bullets, names its altitude, and commits no solution. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/02-ask-probing-questions.md b/plugins/aidd-refine/skills/01-brainstorm/actions/02-ask-probing-questions.md deleted file mode 100644 index 5f07938d..00000000 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/02-ask-probing-questions.md +++ /dev/null @@ -1,30 +0,0 @@ -# 02 - Ask Probing Questions - -Generate questions to challenge assumptions, edge cases, and missing context. - -## Inputs - -- `captured_request` : original bullet points request. - -## Outputs - -List of 3-5 probing questions. - -```markdown -- Question 1? -- Question 2? -``` - -## Depends on - -- `01-capture-request` - -## Process - -1. Analyze `captured_request` for gaps (assumptions, edges, context). -2. Generate targeted questions using `assets/question-templates.md`. -3. Output questions for user response. - -## Test - -- Questions address potential ambiguities in the request. \ No newline at end of file diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/02-probe.md b/plugins/aidd-refine/skills/01-brainstorm/actions/02-probe.md new file mode 100644 index 00000000..b7b130f2 --- /dev/null +++ b/plugins/aidd-refine/skills/01-brainstorm/actions/02-probe.md @@ -0,0 +1,23 @@ +# 02 - Probe + +Ask pointed questions that follow the open thread and challenge the idea's assumptions. + +## Input + +The idea so far and the answers up to now. + +## Output + +A focused set of pointed questions on the live thread, then a wait for the user. + +## Process + +1. **Find the live thread.** Pick the biggest unknown, especially a fork where two materially different builds are still possible. Follow what the last answer opened rather than switching topics. See `@../references/probing.md`. +2. **Probe at altitude.** Ask at the idea's grain, functional or technical. Never drop a level finer into how-to that belongs to planning. +3. **Challenge and stress.** Surface an unstated assumption the moment it appears. Walk concrete limit cases and failure modes, and when it helps ask the user to imagine the idea shipped then failed and name what went wrong. Draw angles from `@../assets/question-angles.md` and tactics from `@../references/probing.md`. +4. **Keep it sharp.** Ask a focused set of pointed questions on the thread, several when they share it, never a question already answered, never a flat checklist. Name the fork plainly when there is one. +5. **Ask and wait.** Put the questions to the user as plain conversation and stop for the answer. + +## Test + +- The output asks pointed questions on the live thread at the idea's altitude, names any fork, surfaces assumptions as they appear, and waits for the user. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/03-integrate-answers.md b/plugins/aidd-refine/skills/01-brainstorm/actions/03-integrate-answers.md deleted file mode 100644 index bae3d892..00000000 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/03-integrate-answers.md +++ /dev/null @@ -1,33 +0,0 @@ -# 03 - Integrate Answers - -Update the request with user responses and determine if more clarification is needed. - -## Inputs - -- `captured_request` : original bullet points request. -- `user_answers` : responses to questions. - -## Outputs - -Updated request and flag for more questions. - -```json -{ - "updated_request": ["- Updated feature 1", "- Updated feature 2"], - "needs_more": true -} -``` - -## Depends on - -- `02-ask-probing-questions` - -## Process - -1. Merge `user_answers` into `captured_request` bullets. -2. Assess if ambiguity remains; set `needs_more`. -3. Output updated request and flag. - -## Test - -- Updated request incorporates answers; `needs_more` accurately reflects clarity. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/03-integrate.md b/plugins/aidd-refine/skills/01-brainstorm/actions/03-integrate.md new file mode 100644 index 00000000..fd729965 --- /dev/null +++ b/plugins/aidd-refine/skills/01-brainstorm/actions/03-integrate.md @@ -0,0 +1,21 @@ +# 03 - Integrate + +Fold the answers in, then judge whether the idea is clear or still hiding ambiguity. + +## Input + +The user's answers and the idea so far. + +## Output + +The updated idea, a leaning when the facts now point one way, and a judgment to keep probing or to finalize. + +## Process + +1. **Fold in.** Absorb the answers into the bullets. Tighten what they sharpened. +2. **Lean when it points.** When the clarified facts favor one option, say the leaning and its tradeoff. Keep finer-grain how-to as a flagged assumption, not a commitment. +3. **Judge the ambiguity.** Decide whether a competent reader could still build two materially different things from what we have. If yes, there is a live thread, hand back to `02-probe`. If no real ambiguity remains, or the user is satisfied, move to `04-finalize`. There is no round count, the idea is done when it is clear, not on a timer. + +## Test + +- The idea reflects the answers, a leaning is stated when the facts point, and the keep-probing-or-finalize judgment rests on whether real ambiguity remains, not on a count. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md b/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md new file mode 100644 index 00000000..401e7a2d --- /dev/null +++ b/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md @@ -0,0 +1,32 @@ +# 04 - Finalize + +Consolidate the clarified idea, flag what stays open, and let the user choose where it lives. + +## Input + +The clarified idea and the conversation so far. + +## Output + +The approved refined idea with its flagged open assumptions and risks, a pointer to the fitting next step, and, when the user picks the file, a markdown file at `aidd_docs/brainstorm/-.md`. + +## Process + +1. **Consolidate.** Write the refined idea as one coherent, intent-level description built from the bullets. No solution, no plan. +2. **Flag the open.** List the assumptions left unanswered and the risks to confirm at design time, so the next step knows them. Never present a guess as settled. +3. **Get approval.** Show the refined idea and the open list, and ask the user to confirm or correct. Wait for the answer. +4. **Point to the next move.** Say in plain words what the refined idea is now ready for, planning it, specifying it, or building it, so the user's next request reaches the right tool on its own. Describe the move, never name a plugin or skill, and never run it. +5. **Offer to persist.** Once approved, present all three destinations and act on the pick. Name all three, persist nothing without the user's choice. + - **File.** Write the document to exactly `aidd_docs/brainstorm/-.md`, where `` is today's date and `` is the idea in kebab-case. The directory and format are fixed, never another path or name. Create `aidd_docs/brainstorm/` if missing. + + | Idea, saved on | File written | + | --- | --- | + | aidd-craft plugin, 2026-03-09 | `aidd_docs/brainstorm/2026_03_09-aidd-craft-plugin.md` | + | dark mode toggle, 2026-11-20 | `aidd_docs/brainstorm/2026_11_20-dark-mode-toggle.md` | + - **Ticket.** Open or append a ticket drawn from the memory and VCS context. + - **Session.** Keep it in the conversation only, write nothing. + +## Test + +- The output is a consolidated intent-level idea plus an explicit list of open assumptions and risks, approved by the user, and it names all three persist destinations and the fitting next move without a `plugin:skill` identifier. +- When the user picks the file, a file exists afterward at `aidd_docs/brainstorm/-.md` and nowhere else. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/04-refine-and-validate.md b/plugins/aidd-refine/skills/01-brainstorm/actions/04-refine-and-validate.md deleted file mode 100644 index af75feea..00000000 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/04-refine-and-validate.md +++ /dev/null @@ -1,33 +0,0 @@ -# 04 - Refine and Validate - -Finalize the request and validate for remaining ambiguity. - -## Inputs - -- `updated_request` : user request with clarification answers - -## Outputs - -Refined request and validation result. - -```json -{ - "refined_request": "Consolidated description", - "is_clear": true, - "issues": [] -} -``` - -## Depends on - -- `03-integrate-answers` - -## Process - -1. Consolidate `updated_request` into coherent description. -2. Check for ambiguity using `references/ambiguity-detection.md`. -3. Output refined request, clarity flag, and any issues. - -## Test - -- Refined request is clear and consolidated; `is_clear` is accurate. diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/05-confirm-approval.md b/plugins/aidd-refine/skills/01-brainstorm/actions/05-confirm-approval.md deleted file mode 100644 index 5b80f7d8..00000000 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/05-confirm-approval.md +++ /dev/null @@ -1,28 +0,0 @@ -# 05 - Confirm Approval - -Present the final refined request and wait for user approval. - -## Inputs - -- `refined_request` from previous action. - -## Outputs - -Approval prompt displayed. - -```text -Does this refined request look correct? (Yes/No) -``` - -## Depends on - -- `04-refine-and-validate` - -## Process - -1. Display `refined_request` clearly. -2. Output approval prompt and wait for response. - -## Test - -- Prompt is displayed with the refined request. diff --git a/plugins/aidd-refine/skills/01-brainstorm/assets/question-angles.md b/plugins/aidd-refine/skills/01-brainstorm/assets/question-angles.md new file mode 100644 index 00000000..8d7c17ee --- /dev/null +++ b/plugins/aidd-refine/skills/01-brainstorm/assets/question-angles.md @@ -0,0 +1,43 @@ +# Question angles + +Prompt banks grouped by topic, to draw from when a thread runs that way. Not a checklist to complete. Pick what fits the live thread, rephrase to the user's domain and altitude, never dump the whole list. + +## Problem and goal + +- What changes once this works, and for whom? +- What does this solve that nothing today solves? +- How will you know it was worth doing? + +## Actors and parts + +- Who or what triggers this? +- Who or what is affected when it runs? +- Which other system, service, or component takes part? + +## Scope and boundaries + +- What is the smallest version that still counts as done? +- What is explicitly out of scope for this iteration? +- Where does this feature stop and another begin? + +## Success criteria + +- How do we verify each behavior works? +- What is the measurable bar, a number, a state, a result set? +- What does a failing case look like? + +## Constraints and dependencies + +- What must already exist for this to run? +- What limits apply, time, cost, platform, data? +- What prior step or external service does this rely on? + +## Edge and failure modes + +Walk these one at a time, keep only the ones that would change what gets built. + +- Boundaries: empty, zero, maximum, one over the limit, duplicate? +- Concurrency: two actors at once, out-of-order, a repeated request? +- Failure: a step fails, a service is down, a timeout, a partial write? +- Bad input: invalid, malformed, or hostile, and how should it answer? +- Absence: the actor offline, the data missing, the dependency not ready? diff --git a/plugins/aidd-refine/skills/01-brainstorm/assets/question-templates.md b/plugins/aidd-refine/skills/01-brainstorm/assets/question-templates.md deleted file mode 100644 index 5c88c836..00000000 --- a/plugins/aidd-refine/skills/01-brainstorm/assets/question-templates.md +++ /dev/null @@ -1,10 +0,0 @@ -# Question Templates - -Reusable categories for probing questions: - -- Who are the primary users? (e.g., customers, employees) -- What platforms or environments? (web, mobile, desktop) -- What are the key assumptions? -- What edge cases should be considered? -- What constraints or limitations exist? -- How does this integrate with existing systems? diff --git a/plugins/aidd-refine/skills/01-brainstorm/references/ambiguity-detection.md b/plugins/aidd-refine/skills/01-brainstorm/references/ambiguity-detection.md deleted file mode 100644 index c1813217..00000000 --- a/plugins/aidd-refine/skills/01-brainstorm/references/ambiguity-detection.md +++ /dev/null @@ -1,16 +0,0 @@ -# Ambiguity Detection - -Signs of unclear requirements: - -- Vague terms like "users", "fast", "easy". -- Missing context (who, what, when, where, why). -- Assumptions not stated. -- No edge cases mentioned. -- Incomplete integration details. - -How to resolve: - -- Ask specific questions. -- Use examples. -- Break down into smaller parts. -- Validate with user confirmation. diff --git a/plugins/aidd-refine/skills/01-brainstorm/references/probing.md b/plugins/aidd-refine/skills/01-brainstorm/references/probing.md new file mode 100644 index 00000000..64583b9d --- /dev/null +++ b/plugins/aidd-refine/skills/01-brainstorm/references/probing.md @@ -0,0 +1,28 @@ +# Probing + +How to dig until an idea is clear. No scoreboard, no fixed round count. Depth comes from following threads, not from ticking topics. + +## Read the altitude first + +An idea sits at a level: functional (what it does and for whom), technical (a design or tooling choice), or mixed. Probe at that level, never one finer. For a technical idea the technical choice is the subject, so engaging it is right. The how-to that implements the choice belongs to planning, leave it as a flagged assumption. + +## Follow the thread + +Each answer opens a new thread. Pull it. The richest threads are forks, where two materially different builds are still possible, for example searching a filename versus searching the full text inside a file. Name the fork and ask which side. Cycling a fixed list of topics gives breadth and no depth. Following the thread gives depth. + +## Tactics to draw from + +Reach for one when it fits, never run them all. + +- **Five whys.** When the stated goal looks like a chosen solution, ask why a few times to reach the real need underneath. +- **Job to be done.** Reframe a named feature as "when [situation], I want [motivation], so I can [outcome]" to separate the job from the solution. +- **Concrete example.** When a term has two readings, ask for one example that fits and one that does not. +- **Premortem.** To surface failures, ask the user to imagine the idea shipped and then failed, and to name what went wrong. Working back from the failure finds modes a generic checklist misses. + +## Flag, never fake + +When a gap stays open at the end, state it as an assumption or a risk to confirm at design time. A reasonable assumption clearly flagged is useful. A guess presented as settled is not. + +## Know when to stop + +The idea is clear enough when a competent reader would build the same thing from it, the forks that change the build are answered or consciously deferred, and the edges and failures have been raised. Stop there, or the moment the user is satisfied. Never stop on a count.