From 36e289ea8bdb66f859bb13395999f74468599117 Mon Sep 17 00:00:00 2001 From: Drew Ritter Date: Wed, 10 Jun 2026 18:28:51 -0700 Subject: [PATCH] refine(skills): reconcile flowchart + EXTREMELY-IMPORTANT with the exception rule; writing-skills carve-out MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 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 --- skills/using-superpowers/SKILL.md | 9 ++++++--- skills/writing-skills/SKILL.md | 2 ++ 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index a93aa08e..5802bcb2 100644 --- a/skills/using-superpowers/SKILL.md +++ b/skills/using-superpowers/SKILL.md @@ -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.) ## 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?"; diff --git a/skills/writing-skills/SKILL.md b/skills/writing-skills/SKILL.md index d7393dc7..49d916a3 100644 --- a/skills/writing-skills/SKILL.md +++ b/skills/writing-skills/SKILL.md @@ -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.