From 4781ab68671f43bbc3769651140f4beecb186bce Mon Sep 17 00:00:00 2001 From: "A. Felipe Cabargas" Date: Thu, 7 May 2026 22:37:06 +0200 Subject: [PATCH 1/2] feat(write-fr): add Phase 4 Verification Gate with five-dimension AC scoring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds an automatic post-assembly verification step to write-feature-request (v1.0.0 → v1.1.0). After Phase 3 assembles the FR, Phase 4 evaluates every AC against all five quality dimensions — Specificity, Testability, Outcome-Focus, Measurability, and Independence (the last dimension was not previously checked). ACs with warning-severity gaps are rewritten inline; blockers reopen Phase 2 for the affected requirement only. The FR is not returned until every AC passes all five dimensions. A Verification Summary table is appended to every FR output so the gate is visible to the user without exposing raw scoring internals. verify-acceptance-criteria is unchanged and continues to work standalone. Co-Authored-By: Claude Sonnet 4.6 --- skills/write-feature-request/SKILL.md | 59 ++++++++++++++++++++------- 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/skills/write-feature-request/SKILL.md b/skills/write-feature-request/SKILL.md index 0a7d349..5707e2b 100644 --- a/skills/write-feature-request/SKILL.md +++ b/skills/write-feature-request/SKILL.md @@ -5,7 +5,7 @@ description: | Use this skill whenever a user needs to author or improve a feature request. Trigger on: "write a feature request", "help me write an FR", "create a feature spec", "draft a feature proposal", "I want to define a new feature", "turn this idea into a feature request", or similar requests. compatibility: "Requires filesystem access to project directory. Works best with markdown and project context documents." -version: 1.0.0 +version: 1.1.0 argument-hint: "[feature idea or problem]" allowed-tools: [Read, Write, Bash] --- @@ -72,7 +72,18 @@ This loop continues until every requirement has at least one valid AC. ### Phase 3 — FR Assembly -Once all ACs are validated, the skill assembles the complete FR in the output format below and returns it to the user. +Once all ACs are validated, the skill assembles the complete FR in the output format below and hands it off to Phase 4. + +### Phase 4 — Verification Gate + +After assembly, every AC in every requirement table is evaluated against the full **five-dimension quality standard**: Specificity, Testability, Outcome-Focus, Measurability, and Independence. This step is automatic — it always runs and the user is not prompted. + +**For each AC that does not pass:** + +- **Blocker-severity gap** — the AC cannot be objectively verified, is internally contradictory, or relies entirely on another AC to be meaningful: the affected requirement is sent back to Phase 2. Phase 2 collects the missing information, regenerates ACs for that requirement only, and Phase 4 re-evaluates. Other requirements are not disturbed. +- **Warning-severity gap** — the AC is testable but imprecise, vague in a bounded way, or rests on an unstated assumption: the AC is rewritten inline. The improved version replaces the original in the FR. No Phase 2 loop. + +**The FR is returned to the user only when every AC across every requirement has at least one ✅ Pass.** Once the gate clears, a Verification Summary is appended to the FR so the user can see the gate was applied. --- @@ -140,34 +151,52 @@ The skill returns the FR in the following Markdown structure: | # | Risk | Likelihood | Impact | Mitigation | |---|---|---|---|---| | 1 | [Risk description] | High / Medium / Low | High / Medium / Low | [Mitigation idea] | + +--- + +## Verification Summary + +| Requirement | ACs | Gate | +|---|---|---| +| REQ-1: [Name] | 2 | ✅ Passed | +| REQ-2: [Name] | 3 | ✅ Revised | +| NFR-1: [Name] | 1 | 🔁 Reopened · resolved | ``` +Gate key: **✅ Passed** — all ACs cleared on first check · **✅ Revised** — one or more ACs were rewritten to resolve warnings · **🔁 Reopened** — a blocker triggered a Phase 2 loop for this requirement; shown as resolved once cleared. + --- ## Evaluation Framework -When generating ACs, the skill evaluates each requirement against the following: +The skill applies two quality gates at different phases: + +- **Phase 2 gate** (four dimensions) — used during AC generation to decide whether an AC can be written at all +- **Phase 4 gate** (five dimensions) — used after FR assembly to verify every assembled AC before the FR is returned ### AC Quality Dimensions -| Dimension | Description | Failure Mode | -|---|---|---| -| **Specificity** | Is the behavior defined precisely enough that two people would interpret it the same way? | Vague verbs ("works well", "is fast", "feels intuitive") | -| **Testability** | Can QA write an automated or manual test that unambiguously passes or fails? | No clear trigger, action, or outcome described | -| **Outcome-Focus** | Does the AC describe what the user experiences, not how the system implements it? | Implementation details creep ("the database must use...") | -| **Measurability** | Are thresholds, counts, or time bounds specified where relevant? | Relative/subjective metrics ("significantly faster") | +| Dimension | Description | Failure Mode | Gate | +|---|---|---|---| +| **Specificity** | Is the behavior defined precisely enough that two people would interpret it the same way? | Vague verbs ("works well", "is fast", "feels intuitive") | Phase 2 + 4 | +| **Testability** | Can QA write an automated or manual test that unambiguously passes or fails? | No clear trigger, action, or outcome described | Phase 2 + 4 | +| **Outcome-Focus** | Does the AC describe what the user experiences, not how the system implements it? | Implementation details creep ("the database must use...") | Phase 2 + 4 | +| **Measurability** | Are thresholds, counts, or time bounds specified where relevant? | Relative/subjective metrics ("significantly faster") | Phase 2 + 4 | +| **Independence** | Does the AC stand alone? Can it be understood and tested without reading other ACs? | AC only makes sense when read alongside another AC | Phase 4 only | ### Severity of AC Gaps -| Severity | Meaning | Action | -|---|---|---| -| 🚫 **Blocker** | AC cannot be written at all — the requirement is too vague or contradictory | Skill pauses and requests clarification before continuing | -| ⚠️ **Warning** | AC can be written but with assumptions — assumptions are made explicit | Skill writes the AC with a note flagging the assumption | -| ✅ **Pass** | AC is fully deterministic and testable | AC is included in the FR | +| Severity | Meaning | Phase 2 Action | Phase 4 Action | +|---|---|---|---| +| 🚫 **Blocker** | AC cannot be written or verified — requirement is too vague, contradictory, or non-independently testable | Skill pauses and requests clarification before continuing | Requirement is sent back to Phase 2; Phase 4 re-evaluates after resolution | +| ⚠️ **Warning** | AC can be written but with assumptions — assumptions are made explicit | Skill writes the AC with a note flagging the assumption | AC is rewritten inline; improved version replaces original in the FR | +| ✅ **Pass** | AC is fully deterministic and testable | AC is included in the FR | AC is confirmed; included as-is | ### Minimum Quality Gate -The FR is only assembled when **all requirements have at least one `✅ Pass` AC**. Requirements with only `⚠️ Warning` ACs are included, but assumptions are surfaced in the Open Questions section for the team to resolve. +The FR is only assembled (Phase 3) when **all requirements have at least one `✅ Pass` AC** from Phase 2. Requirements with only `⚠️ Warning` ACs are included, but assumptions are surfaced in the Open Questions section. + +The FR is only returned to the user (after Phase 4) when **every AC across every requirement has at least one `✅ Pass`** on all five dimensions. Phase 4 rewrites or escalates until this condition is met. --- From c0eee3a3fcbbce6741cf1807badc77b41ee3ab58 Mon Sep 17 00:00:00 2001 From: "A. Felipe Cabargas" Date: Thu, 7 May 2026 22:46:32 +0200 Subject: [PATCH 2/2] =?UTF-8?q?chore(write-fr):=20normalize=20Phase=20?= =?UTF-8?q?=E2=86=92=20Step=20to=20match=20codebase=20convention?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All 9 other skills use "Step"; write-feature-request was the only outlier. Renames Step 1–4 and all prose references accordingly. Co-Authored-By: Claude Sonnet 4.6 --- skills/write-feature-request/SKILL.md | 44 +++++++++++++-------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/skills/write-feature-request/SKILL.md b/skills/write-feature-request/SKILL.md index 5707e2b..e29162a 100644 --- a/skills/write-feature-request/SKILL.md +++ b/skills/write-feature-request/SKILL.md @@ -41,7 +41,7 @@ find . -maxdepth 4 \( -name "FR-*.md" -o -name "feature-request-*.md" \) 2>/dev/ If related FRs are found, surface them before proceeding: *"I found [N] existing feature requests that may be related — [titles]. Is this a new spec, or should we update one of these?"* -### Phase 1 — Information Gathering +### Step 1 — Information Gathering The skill collects four foundational inputs: @@ -54,7 +54,7 @@ The skill collects four foundational inputs: The skill accepts loose, conversational answers and structures them — you don't need to write formally. -### Phase 2 — AC Generation and Quality Gate +### Step 2 — AC Generation and Quality Gate For every requirement collected, the skill attempts to generate at least one concrete Acceptance Criterion (AC). A good AC must be: - **Specific** — unambiguous, with no room for individual interpretation @@ -70,18 +70,18 @@ For every requirement collected, the skill attempts to generate at least one con This loop continues until every requirement has at least one valid AC. -### Phase 3 — FR Assembly +### Step 3 — FR Assembly -Once all ACs are validated, the skill assembles the complete FR in the output format below and hands it off to Phase 4. +Once all ACs are validated, the skill assembles the complete FR in the output format below and hands it off to Step 4. -### Phase 4 — Verification Gate +### Step 4 — Verification Gate After assembly, every AC in every requirement table is evaluated against the full **five-dimension quality standard**: Specificity, Testability, Outcome-Focus, Measurability, and Independence. This step is automatic — it always runs and the user is not prompted. **For each AC that does not pass:** -- **Blocker-severity gap** — the AC cannot be objectively verified, is internally contradictory, or relies entirely on another AC to be meaningful: the affected requirement is sent back to Phase 2. Phase 2 collects the missing information, regenerates ACs for that requirement only, and Phase 4 re-evaluates. Other requirements are not disturbed. -- **Warning-severity gap** — the AC is testable but imprecise, vague in a bounded way, or rests on an unstated assumption: the AC is rewritten inline. The improved version replaces the original in the FR. No Phase 2 loop. +- **Blocker-severity gap** — the AC cannot be objectively verified, is internally contradictory, or relies entirely on another AC to be meaningful: the affected requirement is sent back to Step 2. Step 2 collects the missing information, regenerates ACs for that requirement only, and Step 4 re-evaluates. Other requirements are not disturbed. +- **Warning-severity gap** — the AC is testable but imprecise, vague in a bounded way, or rests on an unstated assumption: the AC is rewritten inline. The improved version replaces the original in the FR. No Step 2 loop. **The FR is returned to the user only when every AC across every requirement has at least one ✅ Pass.** Once the gate clears, a Verification Summary is appended to the FR so the user can see the gate was applied. @@ -163,7 +163,7 @@ The skill returns the FR in the following Markdown structure: | NFR-1: [Name] | 1 | 🔁 Reopened · resolved | ``` -Gate key: **✅ Passed** — all ACs cleared on first check · **✅ Revised** — one or more ACs were rewritten to resolve warnings · **🔁 Reopened** — a blocker triggered a Phase 2 loop for this requirement; shown as resolved once cleared. +Gate key: **✅ Passed** — all ACs cleared on first check · **✅ Revised** — one or more ACs were rewritten to resolve warnings · **🔁 Reopened** — a blocker triggered a Step 2 loop for this requirement; shown as resolved once cleared. --- @@ -171,32 +171,32 @@ Gate key: **✅ Passed** — all ACs cleared on first check · **✅ Revised** The skill applies two quality gates at different phases: -- **Phase 2 gate** (four dimensions) — used during AC generation to decide whether an AC can be written at all -- **Phase 4 gate** (five dimensions) — used after FR assembly to verify every assembled AC before the FR is returned +- **Step 2 gate** (four dimensions) — used during AC generation to decide whether an AC can be written at all +- **Step 4 gate** (five dimensions) — used after FR assembly to verify every assembled AC before the FR is returned ### AC Quality Dimensions | Dimension | Description | Failure Mode | Gate | |---|---|---|---| -| **Specificity** | Is the behavior defined precisely enough that two people would interpret it the same way? | Vague verbs ("works well", "is fast", "feels intuitive") | Phase 2 + 4 | -| **Testability** | Can QA write an automated or manual test that unambiguously passes or fails? | No clear trigger, action, or outcome described | Phase 2 + 4 | -| **Outcome-Focus** | Does the AC describe what the user experiences, not how the system implements it? | Implementation details creep ("the database must use...") | Phase 2 + 4 | -| **Measurability** | Are thresholds, counts, or time bounds specified where relevant? | Relative/subjective metrics ("significantly faster") | Phase 2 + 4 | -| **Independence** | Does the AC stand alone? Can it be understood and tested without reading other ACs? | AC only makes sense when read alongside another AC | Phase 4 only | +| **Specificity** | Is the behavior defined precisely enough that two people would interpret it the same way? | Vague verbs ("works well", "is fast", "feels intuitive") | Step 2 + 4 | +| **Testability** | Can QA write an automated or manual test that unambiguously passes or fails? | No clear trigger, action, or outcome described | Step 2 + 4 | +| **Outcome-Focus** | Does the AC describe what the user experiences, not how the system implements it? | Implementation details creep ("the database must use...") | Step 2 + 4 | +| **Measurability** | Are thresholds, counts, or time bounds specified where relevant? | Relative/subjective metrics ("significantly faster") | Step 2 + 4 | +| **Independence** | Does the AC stand alone? Can it be understood and tested without reading other ACs? | AC only makes sense when read alongside another AC | Step 4 only | ### Severity of AC Gaps -| Severity | Meaning | Phase 2 Action | Phase 4 Action | +| Severity | Meaning | Step 2 Action | Step 4 Action | |---|---|---|---| -| 🚫 **Blocker** | AC cannot be written or verified — requirement is too vague, contradictory, or non-independently testable | Skill pauses and requests clarification before continuing | Requirement is sent back to Phase 2; Phase 4 re-evaluates after resolution | +| 🚫 **Blocker** | AC cannot be written or verified — requirement is too vague, contradictory, or non-independently testable | Skill pauses and requests clarification before continuing | Requirement is sent back to Step 2; Step 4 re-evaluates after resolution | | ⚠️ **Warning** | AC can be written but with assumptions — assumptions are made explicit | Skill writes the AC with a note flagging the assumption | AC is rewritten inline; improved version replaces original in the FR | | ✅ **Pass** | AC is fully deterministic and testable | AC is included in the FR | AC is confirmed; included as-is | ### Minimum Quality Gate -The FR is only assembled (Phase 3) when **all requirements have at least one `✅ Pass` AC** from Phase 2. Requirements with only `⚠️ Warning` ACs are included, but assumptions are surfaced in the Open Questions section. +The FR is only assembled (Step 3) when **all requirements have at least one `✅ Pass` AC** from Step 2. Requirements with only `⚠️ Warning` ACs are included, but assumptions are surfaced in the Open Questions section. -The FR is only returned to the user (after Phase 4) when **every AC across every requirement has at least one `✅ Pass`** on all five dimensions. Phase 4 rewrites or escalates until this condition is met. +The FR is only returned to the user (after Step 4) when **every AC across every requirement has at least one `✅ Pass`** on all five dimensions. Step 4 rewrites or escalates until this condition is met. --- @@ -246,7 +246,7 @@ After generating the FR, the skill automatically identifies: **4. Treat the AC table as a contract.** The AC table in the output is written to be directly usable as a QA checklist. Share it with engineering as-is. -**5. Iterate fast.** You can re-run Phase 2 on any single requirement by asking: "Rework the ACs for requirement [X]" — it will only regenerate that section. +**5. Iterate fast.** You can re-run Step 2 on any single requirement by asking: "Rework the ACs for requirement [X]" — it will only regenerate that section. --- @@ -255,7 +255,7 @@ After generating the FR, the skill automatically identifies: **Trigger:** > "Help me write a feature request for letting users export their data" -**Skill — Phase 1 Questions:** +**Skill — Step 1 Questions:** > Let's build your FR. I'll start with the problem. > > 1. **Problem**: Who is asking to export data, and what are they trying to do with it that they can't do today? Is there any data (support tickets, churn signals, user feedback) that shows how often this is a pain point? @@ -270,7 +270,7 @@ After generating the FR, the skill automatically identifies: *(... conversation continues through outcomes and requirements ...)* -**Skill — Phase 2, AC Blocker Example:** +**Skill — Step 2, AC Blocker Example:** > ⚠️ I can't write a testable AC for requirement **REQ-3: "Export should be fast"** — "fast" is not measurable. > > Can you tell me: