rogee/superpowers
1
0
Fork 0
mirror of https://github.com/obra/superpowers.git synced 2026-06-11 21:29:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

refine(skills): reconcile flowchart + EXTREMELY-IMPORTANT with the exception rule; writing-skills carve-out

Browse Source 
Staff-review findings (4-reviewer panel):
- The skill_flow digraph still routed "yes, even 1%" straight to
  invoke with no exception branch — and this stack's own evidence says
  agents follow flowcharts literally. The flow now passes through
  "Skill's own description exempts this request?" with no/any-doubt →
  invoke.
- The <EXTREMELY-IMPORTANT> block ("you cannot rationalize your way
  out of this") read unconditional; one parenthetical defers to The
  Rule's single carve-out without weakening the block.
- Trimmed the redundant "the description defines the skill's scope"
  clause from The Rule paragraph.
- writing-skills' "descriptions must not carry process" doctrine would
  have had a future editor strip the brainstorming exception and
  silently regress the cost evals; it now distinguishes negative
  triggering conditions (scope — allowed and, per the routing rule,
  required at the description) from workflow summaries (still
  forbidden).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Drew Ritter
2026-06-10 18:28:51 -07:00
parent aecb6c34e6
commit 36e289ea8b
2 changed files with 8 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
skills/using-superpowers/SKILL.md
View File

@@ -12,7 +12,7 @@ If you think there is even a 1% chance a skill might apply to what you are doing
IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
This is not negotiable. This is not optional. You cannot rationalize your way out of this.
This is not negotiable. This is not optional. You cannot rationalize your way out of this. (The single carve-out: a skill whose own description says it does not apply — see The Rule.)
</EXTREMELY-IMPORTANT>
## Instruction Priority
@@ -49,7 +49,7 @@ Skills speak in actions ("dispatch a subagent", "create a todo", "read a file")
**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
**Documented exceptions in a skill's own description are authoritative.** When a description itself says the skill does not apply to a request (e.g. brainstorming's nothing-to-design exception), not invoking it is compliance, not rationalization — the description defines the skill's scope. Any doubt about whether the exception's conditions hold means invoke. Only the skill's description can define such an exception; you cannot infer one.
**Documented exceptions in a skill's own description are authoritative.** When a description itself says the skill does not apply to a request (e.g. brainstorming's nothing-to-design exception), not invoking it is compliance, not rationalization. Any doubt about whether the exception's conditions hold means invoke. Only the skill's description can define such an exception; you cannot infer one.
```dot
digraph skill_flow {
@@ -71,7 +71,10 @@ digraph skill_flow {
"Invoke brainstorming skill" -> "Might any skill apply?";
"User message received" -> "Might any skill apply?";
"Might any skill apply?" -> "Invoke the skill" [label="yes, even 1%"];
"Might any skill apply?" -> "Skill's own description exempts this request?" [label="yes, even 1%"];
"Skill's own description exempts this request?" [shape=diamond];
"Skill's own description exempts this request?" -> "Invoke the skill" [label="no / any doubt"];
"Skill's own description exempts this request?" -> "Respond (including clarifications)" [label="yes, clearly"];
"Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
"Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'";
"Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";

2
skills/writing-skills/SKILL.md
View File

@@ -151,6 +151,8 @@ Concrete results
The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
(Negative triggering conditions are still triggering conditions: a description MAY state when the skill does NOT apply — including its tripwires — and per using-superpowers' Rule such description-level exceptions are authoritative, so they must live here, not only in the body. That is scope, not workflow.)
**Why this matters:** Testing revealed that when a description summarizes the skill's workflow, an agent may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused an agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), the agent correctly read the flowchart and followed the two-stage review process.