feat(directives): scavenge superpowers plugin (using-superpowers, brainstorming, dispatching-parallel-agents, executing-plans): 6 directives

This commit is contained in:
ed
2026-07-04 12:30:15 -04:00
parent 95ef712017
commit 19738b52e7
13 changed files with 243 additions and 2 deletions
@@ -0,0 +1,8 @@
# spec_self_review_four_checks
## v1
**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/brainstorming/SKILL.md`. The directive encodes the Spec Self-Review block at lines 117-124 (placeholder scan + internal consistency + scope check + ambiguity check). Counterweight to the LLM default of shipping specs with TBDs and contradictions and asking the user to spot them.
**Source:** superpowers plugin `skills/brainstorming/SKILL.md:117-124` (Spec Self-Review block)
**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives)
@@ -0,0 +1,28 @@
# Every spec must self-review against four checks — placeholders, internal consistency, scope, ambiguity — before user review
## The four checks
After writing the design spec, the agent runs an inline self-review before handing the spec to the user. The four checks are mandatory and in this order. Any failure is fixed inline; no re-review loop, no waiting for the user to flag the issue.
Per `skills/brainstorming/SKILL.md:117-124` (Spec Self-Review):
> 1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
> 2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
> 3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
> 4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
>
> Fix any issues inline. No need to re-review — just fix and move on.
## Why
Self-review is faster than user-review-loop. The agent catches its own placeholder text or scope overshoot in seconds; the user catches them in minutes-to-hours of round-trip. The user's review time is the expensive resource; the agent's review is cheap. Run the cheap review first.
The four checks are also the four classes of failures that derail implementation. Placeholders produce unfinished code. Inconsistency produces code that contradicts itself. Over-scope produces code that half-implements a feature. Ambiguity produces code that implements the wrong interpretation. Pre-empt all four.
## What this means in practice
- The agent reads its own freshly-written spec ONCE before showing it to the user.
- For each of the four checks, the agent scans the spec for the corresponding failure mode.
- Any failure is fixed by editing the spec file in place; no commit yet (the fix is part of the write).
- The spec the user sees is the spec the agent would write if asked to "write the cleanest possible spec for the same requirement."
- If the agent catches itself wanting to defer a fix ("the user can decide"), the agent fixes it inline per the original protocol.