mirror of
https://github.com/obra/superpowers.git
synced 2026-06-12 21:59:04 +08:00
refine(skills): reconcile flowchart + EXTREMELY-IMPORTANT with the exception rule; writing-skills carve-out
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:
@@ -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.
|
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>
|
</EXTREMELY-IMPORTANT>
|
||||||
|
|
||||||
## Instruction Priority
|
## 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.
|
**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
|
```dot
|
||||||
digraph skill_flow {
|
digraph skill_flow {
|
||||||
@@ -71,7 +71,10 @@ digraph skill_flow {
|
|||||||
"Invoke brainstorming skill" -> "Might any skill apply?";
|
"Invoke brainstorming skill" -> "Might any skill apply?";
|
||||||
|
|
||||||
"User message received" -> "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"];
|
"Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
|
||||||
"Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'";
|
"Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'";
|
||||||
"Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
|
"Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
|
||||||
|
|||||||
@@ -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.
|
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).
|
**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.
|
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.
|
||||||
|
|||||||
Reference in New Issue
Block a user