T-P4VB-task-define-prompts-for-executable-shadow
Status: closed/superseded · Impact: medium · Complexity: small
Auto-generated from a /sdlc:task-work post-mortem. Review and
promote to open/ready before picking up.
When an acceptance criterion describes runtime behavior of a SKILL.md
procedure (no parent script to exercise — only the model executes the
prose), the only way to automate verification is an “executable
shadow” test: a .test.ts under apps/sdlc/skills/<skill>/tests/
that re-encodes the documented logic and asserts against synthetic
inputs. Today, /sdlc:task-define doesn’t prompt for that fallback,
so ACs ship phrased for live verification (“verifiable by reading the
digest log”) that the implementer can’t satisfy without a real run.
Cited by the post-mortem of
T-TJB3-orchestrate-enforces-one-line-verdict, where AC-3 was
reshaped during implementation because the original phrasing required
a live orchestrate tick the harness can’t fake.
apps/sdlc/skills/task-define/SKILL.md walks the operator through
filling each implementation-ready section, but its prompts treat all
ACs the same — there’s no detection for “this AC asserts runtime
behavior of a procedural skill” vs “this AC asserts a code or
artifact change”. Sibling skills (task-ensure-ready, import-planning,
entities-audit) already carry executable-shadow .test.ts suites
under their tests/ directories; the convention exists in the
codebase, just not in task-define’s prompting.
The detection heuristic only ever fires when the consuming project is
this repo (the plugin’s own dev repo) — matching
apps/sdlc/skills/*/SKILL.md in a general skill would be an
SDLC-only carve-out. The project-local skill-extension convention
(apps/sdlc/conventions/project-local-skill-extension.md) exists to
hold exactly this kind of behavior: the general skill declares a hook
point, the consumer-specific heuristic lives under .sdlc/skill-ext/.
Quote from the originating post-mortem: “The task’s AC-3 phrasing (‘verifiable by reading the digest log for that tick’) implied a live-orchestrate test, but orchestrate is procedural prose — there is no parent process to invoke that emits a digest line in CI. A skill-author convention: when an AC asks for ‘live’ verification of a SKILL.md procedure, /sdlc:task-define should prompt for a fallback executable-shadow test rather than letting the prose-only AC ship.”
Proposed
Section titled “Proposed”When the task being defined touches an
apps/sdlc/skills/<skill>/SKILL.md and at least one AC asserts
runtime behavior of that skill, /sdlc:task-define asks the operator
whether an executable-shadow test under
apps/sdlc/skills/<skill>/tests/<name>.test.ts would make the AC
auto-verifiable. If yes, the AC is rewritten to cite the test path.
The heuristic ships as a project-local extension hook in this repo,
not as prose in the general skill; the upstream SKILL.md only
declares the extension point.
Approach
Section titled “Approach”- Declare an extension point in
apps/sdlc/skills/task-define/SKILL.mdafter ACs are drafted, perapps/sdlc/conventions/project-local-skill-extension.md: check for an executable hook at.sdlc/skill-ext/task-define/<event>.sh, invoke it withTASK_FILE=<absolute-path>, informational exit-code semantics, stdout surfaced to the operator. - Ship the hook in this repo: it detects
## Files to touchentries matchingapps/sdlc/skills/*/SKILL.mdAND ACs phrased as runtime assertions (“when X happens, Y holds” / “verifiable by running” / etc.), and emits a note naming the affected AC(s). - When the hook’s note fires, task-define surfaces an
AskUserQuestion: “AC-N asserts runtime behavior of a SKILL.md
procedure. Add an executable-shadow test under
apps/sdlc/skills/<skill>/tests/and rewrite the AC to cite it?” On yes, edit the AC to point at the test path and add the test file to## Files to touch.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
apps/sdlc/skills/task-define/SKILL.md | modify | declare the extension point (path checked, when it fires, input contract, exit-code semantics), referencing the skill-extension convention |
.sdlc/skill-ext/task-define/<event>.sh | new | the heuristic hook: detect SKILL.md touches plus runtime-assertion ACs, emit the shadow-test suggestion |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: Driving
/sdlc:task-definein this repo against a task whoseFiles to touchincludesapps/sdlc/skills/<X>/SKILL.mdand whose AC phrasing asserts runtime behavior fires the executable-shadow prompt at least once. - AC-2: When the operator accepts the prompt, the resulting task
body cites an executable-shadow test path (a
.test.tsunderapps/sdlc/skills/<X>/tests/) in the affected AC AND lists that path in## Files to touch. - AC-3: When the operator declines the prompt, the AC is left unchanged.
Out of scope
Section titled “Out of scope”- Auto-generating the test body (only prompting to add the path and AC reference).
- Detecting non-SKILL.md procedural artifacts (entities, conventions).
Dependencies
Section titled “Dependencies”apps/sdlc/conventions/project-local-skill-extension.md— the hook convention this task routes through (T-R4XL-project-local-skill-extension-mechanism, closed/done).
Discovery context
Section titled “Discovery context”Spawned by /sdlc:task-work post-mortem of T-TJB3-orchestrate-enforces-one-line-verdict on 2026-05-21.
Depends on
Section titled “Depends on”T-R4XL-project-local-skill-extension-mechanism