From c9375f71fe09c17efa5a675e7f2ea92a8c2f1fbb Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Sun, 5 Jul 2026 09:36:08 -0700 Subject: [PATCH] refactor(skills): SDD e2e verification becomes pre-finish offer with disclosure doc The predicate-keyed at-skill-start trigger is replaced by an unconditional offer to the human after the final whole-branch review, before finishing-a-development-branch. The procedure (spec discovery, author/checker/runner flow, fix-wave rules) moves to spec-derived-e2e.md; SKILL.md keeps the offer, a flowchart node, and the Integration reference. Micro-tested 6/6: four controllers at the post-review point all offer before finishing (including under wrap-up-efficiently pressure with the human away); two accepted-offer controllers follow the disclosure doc with the checker run by the controller, one fix subagent, and a fix-diff review gate. Deviation recorded in the design spec. --- ...7-04-spec-derived-scenario-cards-design.md | 11 ++++++ skills/subagent-driven-development/SKILL.md | 39 ++++++------------- .../spec-derived-e2e.md | 39 +++++++++++++++++++ 3 files changed, 62 insertions(+), 27 deletions(-) create mode 100644 skills/subagent-driven-development/spec-derived-e2e.md diff --git a/docs/superpowers/specs/2026-07-04-spec-derived-scenario-cards-design.md b/docs/superpowers/specs/2026-07-04-spec-derived-scenario-cards-design.md index 7b8869f7..ea37787f 100644 --- a/docs/superpowers/specs/2026-07-04-spec-derived-scenario-cards-design.md +++ b/docs/superpowers/specs/2026-07-04-spec-derived-scenario-cards-design.md @@ -227,6 +227,17 @@ shipped form governs. touches, not the plan-named spec alone — plan-named-spec-only wiring skipped the step when the plan named no spec (GREEN iteration 1); the opt-out for spec-less repos is preserved. +- **SDD integration restructured (2026-07-05, maintainer direction):** the + predicate-keyed at-skill-start detection in §3 is replaced by an + unconditional offer to the human after the final whole-branch review and + before finishing-a-development-branch — the human decides, not a spec + predicate. The procedure (spec discovery, author/checker/runner flow, + fix-wave rules) moved to a disclosure doc, + `skills/subagent-driven-development/spec-derived-e2e.md`; SKILL.md keeps + only the offer plus a reference, and the SDD flowchart now carries the + offer node (superseding §3's "flowchart is not modified"). Spec-less + repos surface "nothing to derive from" at offer time instead of skipping + silently. ## Decisions diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index 5937fef2..2694578a 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -63,6 +63,7 @@ digraph process { "Read plan, note context and global constraints, create todos" [shape=box]; "More tasks remain?" [shape=diamond]; "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [shape=box]; + "Offer spec-derived e2e verification (./spec-derived-e2e.md)" [shape=box]; "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen]; "Read plan, note context and global constraints, create todos" -> "Dispatch implementer subagent (./implementer-prompt.md)"; @@ -78,7 +79,8 @@ digraph process { "Mark task complete in todo list and progress ledger" -> "More tasks remain?"; "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"]; "More tasks remain?" -> "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [label="no"]; - "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" -> "Use superpowers:finishing-a-development-branch"; + "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" -> "Offer spec-derived e2e verification (./spec-derived-e2e.md)"; + "Offer spec-derived e2e verification (./spec-derived-e2e.md)" -> "Use superpowers:finishing-a-development-branch"; } ``` @@ -263,32 +265,15 @@ a ledger file, not only in todos. - `git clean -fdx` will destroy the ledger (it's git-ignored scratch); if that happens, recover from `git log`. -## Optional: Spec-Derived E2E Verification +## Before Finishing: Offer E2E Verification -Applies only when a spec governing the code the plan touches — the spec -the plan implements, or a repo spec covering that surface — contains an -"E2E scenario cards" section, or your human partner asked for end-to-end -verification. Otherwise this section does not apply — skip it entirely. - -- At skill start, when you read the plan, open the spec it names — and if - it names none, check the repo's spec directory (e.g. - `docs/superpowers/specs/`) for specs governing the code the plan - touches — and check for an "E2E scenario cards" section. If present, - add a pending "spec-derived e2e verification" item to your todo list - and the progress ledger so compaction cannot lose it. -- After the final whole-branch review passes: use - superpowers:agentic-end-to-end-testing. Dispatch a card-author subagent - per its authoring-cards-from-a-spec.md, run its - scripts/check-cards-against-spec yourself on the author's output - (self-attestation is not the gate), then dispatch a runner subagent per - its runner-prompt.md against the built branch. -- Card FAILs are findings: dispatch ONE fix subagent with the complete - list, then re-run the failed cards. The card author never fixes. Fix-wave - commits land after the final review, so give the fix diff its own - task-review gate before finishing — a green re-run alone does not ship - unreviewed changes. -- Results land before superpowers:finishing-a-development-branch, so - "ready to merge" includes live-scenario evidence. +After the final whole-branch review passes and before +superpowers:finishing-a-development-branch, offer your human partner +spec-derived e2e verification: scenario cards derived from the governing +spec, run live against the built branch. If they accept — or asked for +end-to-end verification earlier — follow +[spec-derived-e2e.md](spec-derived-e2e.md). If they decline, proceed to +finishing. ## Prompt Templates @@ -436,7 +421,7 @@ Done! - **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing) - **superpowers:writing-plans** - Creates the plan this skill executes - **superpowers:requesting-code-review** - Code review template for the final whole-branch review -- **superpowers:agentic-end-to-end-testing** - Optional spec-derived e2e verification after the final review (see Optional: Spec-Derived E2E Verification) +- **superpowers:agentic-end-to-end-testing** - Spec-derived e2e verification, offered before finishing (see [spec-derived-e2e.md](spec-derived-e2e.md)) - **superpowers:finishing-a-development-branch** - Complete development after all tasks **Subagents should use:** diff --git a/skills/subagent-driven-development/spec-derived-e2e.md b/skills/subagent-driven-development/spec-derived-e2e.md new file mode 100644 index 00000000..10359cfd --- /dev/null +++ b/skills/subagent-driven-development/spec-derived-e2e.md @@ -0,0 +1,39 @@ +# Spec-Derived E2E Verification + +Live end-to-end evidence for the branch: scenario cards derived from the +governing spec, run against the built code. Results land before +superpowers:finishing-a-development-branch, so "ready to merge" includes +live-scenario evidence, not just review verdicts. + +## Finding the governing spec + +Open the spec the plan names. If the plan names none, check the repo's spec +directory (e.g. `docs/superpowers/specs/`) for specs governing the code the +plan touches. + +- Spec with an "E2E scenario cards" section: cards derive from the table's + falsification lines verbatim. +- Spec without the section: the bootstrap path in + superpowers:agentic-end-to-end-testing's authoring-cards-from-a-spec.md + backports a table from the spec's requirements (flagged for human review). +- No governing spec at all: there is nothing to derive cards from. Tell your + human partner and proceed to finishing — or they can write a spec first + and re-run the offer. + +## Procedure + +Use superpowers:agentic-end-to-end-testing: + +1. Dispatch a card-author subagent per its authoring-cards-from-a-spec.md. +2. Run its scripts/check-cards-against-spec yourself on the author's output + — self-attestation is not the gate. +3. Dispatch a runner subagent per its runner-prompt.md against the built + branch. + +## Failure handling + +Card FAILs are findings: dispatch ONE fix subagent with the complete list, +then re-run the failed cards. The card author never fixes. Fix-wave commits +land after the final whole-branch review, so give the fix diff its own +task-review gate before finishing — a green re-run alone does not ship +unreviewed changes.