From 8be453b361e95a4c0ee0ece425ace80cad856f1c Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Tue, 3 Nov 2026 12:35:37 +0100 Subject: [PATCH] feat(skills)!: add kvb-create-requirement and kvb-think-brainstorm, rename kvb-create-feature to kvb-think-gaps kvb-create-requirement asks for the context, runs kvb-think-listen and kvb-think-brainstorm, then drafts one requirement with a user story, operator-confirmed decisions, a Mermaid approach flowchart with emoji phases, a test loop and an operator feedback checkpoint per stage, checkbox acceptance criteria grouped by area, and a Tests group with unit, integration and e2e (n/a with a reason). It writes only on the operator's Write it and stops with an offer to hand over to kvb-create-plan. kvb-think-brainstorm generates options through seven fixed lenses, scores them on value, effort and risk, and hands the best two or three over. kvb-create-feature becomes kvb-think-gaps: it still finds and ranks missing work but delegates every pick to kvb-create-requirement, so the requirement template lives in one place. Operator order 2026-11-03. BREAKING CHANGE: /kvb-create-feature is now /kvb-think-gaps. Co-Authored-By: Claude Opus 5.5 --- README.md | 17 +++- skills/kvb-create-requirement/SKILL.md | 80 +++++++++++++++++++ skills/kvb-think-brainstorm/SKILL.md | 45 +++++++++++ .../SKILL.md | 50 +++++------- 4 files changed, 156 insertions(+), 36 deletions(-) create mode 100644 skills/kvb-create-requirement/SKILL.md create mode 100644 skills/kvb-think-brainstorm/SKILL.md rename skills/{kvb-create-feature => kvb-think-gaps}/SKILL.md (62%) diff --git a/README.md b/README.md index a9f8c36..e35cba4 100644 --- a/README.md +++ b/README.md @@ -31,8 +31,10 @@ flowchart LR think --> think_explain[kvb-think-explain] think --> think_dialectic[kvb-think-dialectic] think --> think_criticize[kvb-think-criticize] + think --> think_brainstorm[kvb-think-brainstorm] + think --> think_gaps[kvb-think-gaps] create --> create_plan[kvb-create-plan] - create --> create_feature[kvb-create-feature] + create --> create_requirement[kvb-create-requirement] code --> code_scope_guard[kvb-code-scope-guard] code --> code_no_defaults[kvb-code-no-defaults] code --> code_no_comments[kvb-code-no-comments] @@ -91,10 +93,12 @@ flowchart LR explain[kvb-think-explain] dialectic[kvb-think-dialectic] criticize[kvb-think-criticize] + brainstorm[kvb-think-brainstorm] + gaps[kvb-think-gaps] end subgraph cat_create [create] plan[kvb-create-plan] - auto_feature[kvb-create-feature] + requirement[kvb-create-requirement] end subgraph cat_code [code] scope_guard[kvb-code-scope-guard] @@ -203,8 +207,13 @@ flowchart LR criticize --> active_listening sceptic --> dialectic sceptic --> no_defaults - auto_feature --> sceptic - auto_feature --> active_listening + gaps --> sceptic + gaps --> active_listening + gaps --> requirement + requirement --> active_listening + requirement --> brainstorm + requirement -. offer .-> plan + brainstorm --> dialectic plan --> robot plan --> active_listening diff --git a/skills/kvb-create-requirement/SKILL.md b/skills/kvb-create-requirement/SKILL.md new file mode 100644 index 0000000..cc15adc --- /dev/null +++ b/skills/kvb-create-requirement/SKILL.md @@ -0,0 +1,80 @@ +--- +name: kvb-create-requirement +description: > + Write a requirement: user story, decisions, Mermaid approach, acceptance + criteria, tests. Trigger on /kvb-create-requirement, "requirement + schreiben", or a kvb-think-gaps pick. +--- + +Writes requirements, never implementations. Nothing touches disk before the +operator picks `Write it`. + +## Step 1: context + +Ask the operator for the context first, in one open question: what should +change, for whom, and why now. A candidate handed over by the +`kvb-think-gaps` skill already carries it. Read what the answer points to +(code, issues, logs, existing requirements) before the next step. + +## Step 2: listen + +Run the `kvb-think-listen` skill until scope, constraints, the definition of +done and every operator-only decision are fixed. Its answers become the +Decisions section. + +## Step 3: brainstorm + +Run the `kvb-think-brainstorm` skill on the approach. The operator's pick +becomes a decision; each rejected option stays there with its reason. + +## Step 4: draft + +Location, filename and numbering follow the project's existing requirement +documents; read them first, and ask when there are none. One feature per +document: a title that needs "and" is two requirements. Sections in this +order: + +1. `# - ` +2. `## User Story`: "As a <role>, I want <capability>, so that <benefit>." +3. `## Decisions (operator-confirmed <YYYY-MM-DD>; do not re-litigate)`: + numbered, a bold keyword first, rejected alternatives with their reason. +4. `## Approach`: one Mermaid `flowchart TD` over the whole procedure, one + `subgraph` per phase with an emoji title and an emoji in every node: + + ```mermaid + flowchart TD + subgraph P["๐Ÿงญ 0 ยท Preparation"] + P1["๐Ÿ“‹ Write requirement"] --> P2{"โœ… Operator approves?"} + P2 -- "โœ๏ธ corrections" --> P1 + end + P2 -- "๐Ÿค– yes" --> A1 + subgraph A["๐Ÿ› ๏ธ A ยท Implementation"] + A1["๐Ÿงฉ Change"] --> A2{"๐Ÿงช Tests green?"} + A2 -- "๐Ÿ”ด no: fix" --> A1 + A2 -- "๐ŸŸข yes" --> AF{"๐Ÿ’ฌ Operator feedback?"} + AF -- "โœ๏ธ changes" --> A1 + end + AF -- "๐Ÿ‘ fits" --> D1["๐Ÿ Review, commit with operator OK, hand-over"] + ``` + + Every verifiable stage gets its test loop and an operator feedback + checkpoint; a user-visible change shows screenshots at that checkpoint. +5. `## Acceptance Criteria`: grouped under `###` per area. Each item is a + `- [ ]` that one check proves or disproves on its own: a command, a + `file:line`, a test name, an observable state. No "should", no "works + well". +6. `### Tests`, the last group: `Unit`, `Integration` and `E2E`, each with + its criteria. A level that cannot apply stays with `n/a: <reason>`. + +## Step 5: confirm and write + +Show the full draft, then `AskUserQuestion`: `Write it` / `Revise it` / +`Discard`. Revise loops back to the step the correction touches. Write only +on `Write it`; lint the file with the project's markdown linter on the +resource chair's grant (the `kvb-org-organize` skill). + +## Step 6: hand over + +Stop after writing. Offer in one line to run the `kvb-create-plan` skill, +which hands the plan to the `kvb-org-robot` skill; never start the +implementation without the operator's yes. diff --git a/skills/kvb-think-brainstorm/SKILL.md b/skills/kvb-think-brainstorm/SKILL.md new file mode 100644 index 0000000..6b51cb8 --- /dev/null +++ b/skills/kvb-think-brainstorm/SKILL.md @@ -0,0 +1,45 @@ +--- +name: kvb-think-brainstorm +description: > + Generate options through fixed lenses, then score and narrow them. Trigger + on /kvb-think-brainstorm, "brainstorm", or when a skill needs alternatives. +--- + +Generate first, judge second: no option is scored before all are on the +table. + +## Step 1: frame + +One line: the problem, who has it, and which constraints are fixed. Ask the +operator only for what the context does not give, by the `kvb-think-listen` +skill's rules. + +## Step 2: diverge + +At least one option per lens, none judged yet: + +- **Obvious**: what anyone would try first. +- **Minimal**: the smallest change that helps at all. +- **Maximal**: the version without a budget limit. +- **Inversion**: solve the opposite problem, or remove the need. +- **Analogy**: how another domain solves a problem of the same shape. +- **Drop a constraint**: what one fixed constraint, gone, makes possible. +- **Reuse**: what the repository, the platform or a dependency already has. + +## Step 3: converge + +Rate every option on value, effort and risk (`low`, `medium`, `high`), +merge duplicates, and drop each option another one beats on all three. + +## Step 4: hand over + +The best two or three go to the calling skill, or to the operator through +`AskUserQuestion` with `multiSelect: false`, the recommended option first. +A consequential choice runs through the `kvb-think-dialectic` skill before +it is offered. + +## Output + +| Option | Lens | Value | Effort | Risk | Kept | + +Dropped options stay in the table with the option that beat them. diff --git a/skills/kvb-create-feature/SKILL.md b/skills/kvb-think-gaps/SKILL.md similarity index 62% rename from skills/kvb-create-feature/SKILL.md rename to skills/kvb-think-gaps/SKILL.md index 41a50ff..2172abd 100644 --- a/skills/kvb-create-feature/SKILL.md +++ b/skills/kvb-think-gaps/SKILL.md @@ -1,23 +1,21 @@ --- -name: kvb-create-feature +name: kvb-think-gaps description: > - Derive missing work (principles pass for structural flaws, usability pass for - missing features) and write requirement documents after confirmation. - Trigger on /kvb-create-feature, "was fehlt noch", "welche features brauchen - wir", or asked what to build next. + Find and rank missing work (structural flaws, missing features); each pick + goes to kvb-create-requirement. Trigger on /kvb-think-gaps, "was fehlt + noch", or asked what to build next. --- Two blind spots produce different work: the code has defects of structure, the product has gaps of use. This skill runs both lenses, ranks what comes -out, and lets the operator choose โ€” it writes requirement documents, never -implementations. +out, and lets the operator choose. It writes no file; the +`kvb-create-requirement` skill writes the requirement for every pick. ## Step 1: fix the scope Name the target in one line: repository, subsystem, role, or user-facing -surface. Read the project's existing requirement documents first โ€” their -location, filename convention, and section structure are the template, and -an already-written requirement is not a finding. +surface. Read the project's existing requirement documents first; an +already-written requirement is not a finding. ## Step 2: the principles pass @@ -66,33 +64,21 @@ option a real alternative โ€” never one option plus filler: 2. **Which shape** the chosen one takes โ€” for a feature typically `Minimal version that unblocks the user`, `Full version`, `Fix the underlying structure instead`, `Document the limitation and defer`. -3. **Scope boundary** โ€” what is explicitly out of scope, when the candidate - could grow in more than one direction. -4. **Placement** โ€” which requirement file or directory receives it, when the - project has more than one. -Never assume an answer, never fold two decisions into one option, and never -write a file before the answers are in. +Never assume an answer and never fold two decisions into one option. -## Step 5: write the requirements +## Step 5: hand over -One document per feature โ€” a requirement that needs "and" in its title is -two requirements. Follow the project's existing template; when there is -none, keep it to: problem with its evidence, the decided scope and its -boundary, definition of done as checkable criteria, and the alternatives the -operator rejected with the reason. - -Show the drafted document and ask for a final `Write it` / `Revise it` / -`Discard` before touching disk. +Run the `kvb-create-requirement` skill once per chosen candidate. Its +context step starts from the candidate's evidence and chosen shape; the +rejected shapes go into its Decisions section. ## Rules -- Requirements only: no implementation, no refactor, no staging as part of - this skill. -- Every requirement traces to evidence โ€” a `file:line`, a failing path, a - missing artifact. A requirement whose justification is "would be nice" is - not written. -- Record the rejected alternatives inside the document; the next reader - needs to know what was already considered and dismissed. +- Findings only: no file, no implementation, no refactor, no staging as + part of this skill. +- Every candidate traces to evidence โ€” a `file:line`, a failing path, a + missing artifact. A candidate whose justification is "would be nice" is + dropped. - Close with the `kvb-check-confidence` skill's numbers for the analysis: how sure the gaps are real, and what the passes did not cover.