@sassywares/skills 0.5.10 → 0.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
   "type": "module",
   "license": "MIT",

package/skills/sassy-skill/SKILL.md

@@ -47,17 +47,19 @@ Internal is the only one that ships to everyone. Never choose it silently: once
 
 Paths in the table are the defaults. Harnesses also read `skills` arrays in settings and installed packages, so a skill may live elsewhere — write down where it actually went.
 
-## Shape rule — the lean rule
+## Shape rule — split on outcomes, not on topics
 
-- **Default to one `SKILL.md`.**
-- Add `references/` **only** for content that is **conditionally read** (or genuinely bulky and only sometimes needed). A reference that is read on *every* run saves nothing and may cost a little.
-- Keep `SKILL.md` an index: outcome → hard rules → workflow → explicit pointers ("read `references/x.md` before doing Y").
-- Never bury conditional detail in a monolithic `SKILL.md`.
+- **One `SKILL.md` is the default, but it is a decision, not a reflex.** Length never decides the shape; the paths do.
+- **Split whenever the skill branches into paths that end differently.** A mode, trigger, or branch that writes a different thing, forbids a different thing, or is never needed in the same run as its sibling gets its own `references/<path>.md` — **even at three paragraphs**. How small each path is does not matter: what matters is that a model running path A never reads path B's instructions next to A's. Divergent outcomes sharing one file bleed into each other, and the bleed looks like helpfulness until it has already written the wrong thing. Think ahead when you write it, not after the first misfire.
+- **Never split a shared surface.** What every path needs — ids, board or table values, hard rules, API quirks, house style — stays in `SKILL.md`, or each path pays to load it and they drift apart. One reference per **outcome**, never one per **section**: `references/` holding five short topic files is the oversplit, and it makes routing vaguer, not sharper.
+- **`SKILL.md` becomes routing.** State the dispatch explicitly — a table naming exactly one reference per path, plus "read that one only". That sentence is what prevents the bleed; a pointer buried in a paragraph does not.
+- A reference that is read on *every* run saves nothing and may cost a little, so it belongs in the body.
+- Keep `SKILL.md` an index: outcome → hard rules → workflow → explicit pointers ("read `references/x.md` before doing Y"). Never bury path-specific detail in a monolithic file.
 
 ## Workflow
 
 1. **Intake.** Settle the mode (above), then what the skill does, when it should trigger, and **where it lives** — internal, project, or user (see above). Ask; do not infer from the cwd. In `mode:retune`, read the existing skill and name the specific failure (won't trigger, too long, wrong steps, stale, wrong scope). In `mode:verify`, read it, run the checklist and Verify, report, and stop without writing.
-2. **Choose the shape.** Single file, or `SKILL.md` + `references/` per the rule above.
+2. **Choose the shape — enumerate the outcome paths first.** List the ways a run can end (file / comment / move a state; plan / implement / ship; create / retune / verify). Every path that ends differently gets its own reference; what all paths share stays in the body. Then write the dispatch table that names exactly one reference per path. Splitting by outcome is cheap; a misfire because two outcomes shared a page is not.
 3. **Write the frontmatter.** A description that states both what and when.
 4. **Write the body.** Outcome, a hard-rules table, the workflow, and reference pointers. Plain English. Structured output where the skill returns a result. Match this setup's house style.
 5. **Self-check** against the checklist below.
@@ -69,6 +71,8 @@ Paths in the table are the defaults. Harnesses also read `skills` arrays in sett
 - [ ] `description`: states what **and** when, ≤1024, not vague.
 - [ ] Frontmatter is valid YAML with the required fields.
 - [ ] Every `references/…` path exists and is pointed to explicitly in the body.
+- [ ] Each outcome path that ends differently has its own reference, and the body dispatches to exactly one of them per run.
+- [ ] No reference exists merely because its content was a separate section — that is oversplitting, not shaping.
 - [ ] The body is lean; no always-read detail needlessly hidden in a reference.
 - [ ] No secrets, and no capability the skill cannot actually use.
 
@@ -78,6 +82,7 @@ In `mode:retune`, change the **smallest** thing that fixes the named failure:
 
 - **Won't trigger** → rewrite the description (what + when, concrete verbs).
 - **Too long / bloated** → extract conditional content to `references/`, or delete what never gets used.
+- **One path's rules bleed into another's** (a mode doing the neighbouring mode's job) → that is a shape bug, not a wording bug: split the divergent outcomes into `references/`, one file per path, and give the body a dispatch table that names exactly one file per mode.
 - **Wrong or stale steps** → correct the workflow against the current tree.
 - **Wrong scope** → move it between internal, project, and user. Moving into the suite is a release; moving out of it means the next release drops the skill for everyone.