From 1d368d4b5d6f9a9fb0090f2462527644bd51ab48 Mon Sep 17 00:00:00 2001 From: Mathias Date: Sat, 29 Aug 2026 14:50:14 +0200 Subject: [PATCH] docs(skills): drop the Mode 2 routing notes, fix the contributing steps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Seven skills carried a `## Mode 2 Routing Note` citing a routing pod ("Plan 6") that does not exist. Several admitted in their own text that nothing about the skill changes between modes — so it was roughly ten lines of context on every load for zero behavioural effect. The content is not worthless, just not per-skill: it now lives as one table in README.md, with the caveat that nothing depends on it. The related line inside the session_log sections stays, because that one does motivate behaviour — but it no longer cites a component that has never shipped. It now says what is true: pass-rate is what a future routing decision would be based on, and a skill that never logs contributes no evidence either way. While in README: the contributing steps were stale enough to fail CI for anyone who followed them. They said to add a row to SKILLS_INDEX.md by hand — the table is generated now, and `task check` fails on a hand-edited diff — and listed none of the four frontmatter keys the gates require. Step 4 now names the pressure-test bar from #19 rather than leaving it to be discovered. Closes #36 Bump-Type: patch --- README.md | 45 ++++++++++++++++++++++++--- skills/cad-babysit/SKILL.md | 6 ---- skills/code-review/SKILL.md | 6 +--- skills/debug/SKILL.md | 6 +--- skills/feature-spec/SKILL.md | 6 +--- skills/session-retrospective/SKILL.md | 6 +--- skills/spec-driven-dev/SKILL.md | 2 +- skills/tdd/SKILL.md | 6 +--- skills/trainer/SKILL.md | 6 +--- 9 files changed, 47 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index ca1c9f9..ce74d00 100644 --- a/README.md +++ b/README.md @@ -130,13 +130,48 @@ before `task skills:install`; default is `main` for always-current. ## Contributing a skill -1. Add a directory `/`. -2. Create `/SKILL.md` — start with one-paragraph - purpose, then triggers ("use when …"), then mechanics. -3. Add a row to `SKILLS_INDEX.md` (description + use-when). -4. Commit directly to `main`. Conventional-commit prefix +1. Add a directory `skills//`. +2. Create `skills//SKILL.md` with this frontmatter — all four + keys are gated by `task check`, and the index table is generated from the + last three: + + ```yaml + --- + name: + surfaces: [claude-code, library] # any of claude-code | library | chat + summary: "" + use_when: "" + description: + --- + ``` + + Then: one-paragraph purpose, triggers ("use when …"), mechanics. +3. Run `task index` and commit the regenerated `SKILLS_INDEX.md`. Do **not** + hand-edit the table — `task check` regenerates it and fails on a diff. +4. Pressure-test it before shipping: run the scenario against a subagent that + does *not* have the skill, write the skill against what that run actually + did, then re-run with it. See `superpowers-writing-skills` and #19. +5. Commit directly to `main`. Conventional-commit prefix (`feat:` / `fix:` / `docs:`). Add `Bump-Type: minor` footer when adding a new skill or expanding scope; default patch covers edits. This repo is markdown-only and public — never include secrets, client names, or anything under NDA in a skill. + +## Mode 2 routing candidates + +These notes used to sit in each SKILL.md as a `## Mode 2 Routing Note` section. +They changed nothing about how the skill is invoked — several said so outright — +and cost context on every load, so they live here instead. Nothing in the repo +depends on this table; it is a record of which skills looked mechanical enough +to route to a local model, should a routing layer ever exist. + +| Skill | Note | +|---|---| +| `cad-babysit` | Phases 2-4 (reading comments/logs, classifying fault vs outcome) are judgment-heavy and should stay Mode 1. Phase 1 (running `cad stuck` and grouping its output) is mechanical and a Mode 2 routing candidate once Plan 6 ships the routing pod. | +| `code-review` | This skill is invoked identically in Mode 1 (cloud Claude) and Mode 2 (client-local with supervisor routing). The routing layer (Plan 6) does not exist yet; treat this skill as Mode 1 only for now. Findings format and severity classification are unchanged across modes. | +| `debug` | This skill produces high-volume mechanical output (hypothesis enumeration) and is a candidate for Mode 2 routing to a local model in the future. Until Plan 6 ships the routing pod, treat as Mode 1 only. The hypothesis format and discipline are identical regardless of which model generates them. | +| `feature-spec` | Spec writing requires interpretation of intent and tradeoff reasoning — work where Claude generally outperforms a 9-13B local model. This skill is intentionally **not** a Mode 2 routing candidate. In Mode 2, the routing layer should leave `feature-spec` calls on Claude. | +| `session-retrospective` | Reading long session logs and pulling themes is high-volume, mechanical pattern-recognition work — a strong Mode 2 routing candidate. Until Plan 6 ships the routing pod, treat as Mode 1 only. | +| `tdd` | This skill is invoked identically whether the agent is running in Mode 1 (cloud Claude, no routing) or Mode 2 (client-local, supervisor routing layer). The routing pod (Plan 6) does not exist yet; until it does, treat this skill as Mode 1 only. The discipline does not change between modes — only the model behind the call. | +| `trainer` | Trainer is the same shape as `session-retrospective` — long-context reading, mechanical filtering — and is a Mode 2 routing candidate. Until Plan 6, treat as Mode 1 only. | diff --git a/skills/cad-babysit/SKILL.md b/skills/cad-babysit/SKILL.md index 7369423..f00eef9 100644 --- a/skills/cad-babysit/SKILL.md +++ b/skills/cad-babysit/SKILL.md @@ -247,12 +247,6 @@ decide - `fail` — the phase could not be completed (e.g. `cad stuck` errored, Gitea was unreachable). - `skip` — phase intentionally skipped (e.g. Phase 3 skipped because Phase 2 was conclusive). -## Mode 2 Routing Note - -Phases 2-4 (reading comments/logs, classifying fault vs outcome) are judgment-heavy and should -stay Mode 1. Phase 1 (running `cad stuck` and grouping its output) is mechanical and a Mode 2 -routing candidate once Plan 6 ships the routing pod. - ## Cross-References - Depends on `mathias/cad#14`'s `cad stuck` query — this skill is the ritual around it, not a diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 9ef66d3..5f8cb82 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -262,7 +262,7 @@ treats `pass` as success, `fail` as failure, `skip` as neither. - `fail` — the phase's intended outcome was NOT reached. - `skip` — phase was skipped intentionally. -**Why this matters:** the routing pod (Plan 6) reads pass-rate to decide whether to route a future call to a local model. If your skill never logs, the routing pod sees no data. +**Why this matters:** pass-rate is what a future routing decision would be based on — whether a given call can be served by a local model instead of a cloud one. A skill that never logs contributes no evidence either way. ## Common Go Anti-Patterns @@ -285,7 +285,3 @@ treats `pass` as success, `fail` as failure, `skip` as neither. - Load `refactoring` skill when recommending fixes - Load `test-design` skill for reviewing test quality - Load `solid` skill for SOLID principle violations - -## Mode 2 Routing Note - -This skill is invoked identically in Mode 1 (cloud Claude) and Mode 2 (client-local with supervisor routing). The routing layer (Plan 6) does not exist yet; treat this skill as Mode 1 only for now. Findings format and severity classification are unchanged across modes. diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index 290da99..91bca8a 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -163,11 +163,7 @@ treats `pass` as success, `fail` as failure, `skip` as neither. - `fail` — the phase's intended outcome was NOT reached. - `skip` — phase was skipped intentionally. -**Why this matters:** the routing pod (Plan 6) reads pass-rate to decide whether to route a future call to a local model. If your skill never logs, the routing pod sees no data. - -## Mode 2 Routing Note - -This skill produces high-volume mechanical output (hypothesis enumeration) and is a candidate for Mode 2 routing to a local model in the future. Until Plan 6 ships the routing pod, treat as Mode 1 only. The hypothesis format and discipline are identical regardless of which model generates them. +**Why this matters:** pass-rate is what a future routing decision would be based on — whether a given call can be served by a local model instead of a cloud one. A skill that never logs contributes no evidence either way. ## Cross-References diff --git a/skills/feature-spec/SKILL.md b/skills/feature-spec/SKILL.md index 572af74..bf63363 100644 --- a/skills/feature-spec/SKILL.md +++ b/skills/feature-spec/SKILL.md @@ -254,11 +254,7 @@ treats `pass` as success, `fail` as failure, `skip` as neither. - `fail` — the phase's intended outcome was NOT reached (spec rejected, blocked on unresolved questions). - `skip` — phase was skipped intentionally. -**Why this matters:** the routing pod (Plan 6) reads pass-rate to decide whether to route a future call to a local model. If your skill never logs, the routing pod sees no data. - -## Mode 2 Routing Note - -Spec writing requires interpretation of intent and tradeoff reasoning — work where Claude generally outperforms a 9-13B local model. This skill is intentionally **not** a Mode 2 routing candidate. In Mode 2, the routing layer should leave `feature-spec` calls on Claude. +**Why this matters:** pass-rate is what a future routing decision would be based on — whether a given call can be served by a local model instead of a cloud one. A skill that never logs contributes no evidence either way. ## Cross-References diff --git a/skills/session-retrospective/SKILL.md b/skills/session-retrospective/SKILL.md index 1c090d9..d31fb5d 100644 --- a/skills/session-retrospective/SKILL.md +++ b/skills/session-retrospective/SKILL.md @@ -125,11 +125,7 @@ treats `pass` as success, `fail` as failure, `skip` as neither. - `fail` — the phase's intended outcome was NOT reached (retrospective could not produce coherent candidates). - `skip` — phase was skipped intentionally (no novel learnings worth surfacing). -**Why this matters:** the routing pod (Plan 6) reads pass-rate to decide whether to route a future call to a local model. If your skill never logs, the routing pod sees no data. - -## Mode 2 Routing Note - -Reading long session logs and pulling themes is high-volume, mechanical pattern-recognition work — a strong Mode 2 routing candidate. Until Plan 6 ships the routing pod, treat as Mode 1 only. +**Why this matters:** pass-rate is what a future routing decision would be based on — whether a given call can be served by a local model instead of a cloud one. A skill that never logs contributes no evidence either way. ## Cross-References diff --git a/skills/spec-driven-dev/SKILL.md b/skills/spec-driven-dev/SKILL.md index 9634193..7811579 100644 --- a/skills/spec-driven-dev/SKILL.md +++ b/skills/spec-driven-dev/SKILL.md @@ -341,7 +341,7 @@ treats `pass` as success, `fail` as failure, `skip` as neither. - `fail` — the phase's intended outcome was NOT reached (gate blocked, rework required). - `skip` — phase was skipped intentionally. -**Why this matters:** the routing pod (Plan 6) reads pass-rate to decide whether to route a future call to a local model. If your skill never logs, the routing pod sees no data. +**Why this matters:** pass-rate is what a future routing decision would be based on — whether a given call can be served by a local model instead of a cloud one. A skill that never logs contributes no evidence either way. ## Cross-References diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index 14840f0..0effa0a 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -419,7 +419,7 @@ treats `pass` as success, `fail` as failure, `skip` as neither. - `fail` — the phase's intended outcome was NOT reached (test compiled when it shouldn't, test still fails after green attempt, refactor broke tests). - `skip` — phase was skipped intentionally (e.g. refactor not warranted). -**Why this matters:** the routing pod (Plan 6) reads pass-rate to decide whether to route a future `tdd` call to a local model. If your skill never logs, the routing pod sees no data and may default-route or default-not-route in a way that doesn't reflect real performance. +**Why this matters:** pass-rate is what a future routing decision would be based on — whether a `tdd` call can be served by a local model instead of a cloud one. A skill that never logs contributes no evidence either way, and a decision made on no evidence is a coin flip wearing a metric. ## Final Rule @@ -429,7 +429,3 @@ Otherwise → not TDD ``` No exceptions without Mathias's permission. - -## Mode 2 Routing Note - -This skill is invoked identically whether the agent is running in Mode 1 (cloud Claude, no routing) or Mode 2 (client-local, supervisor routing layer). The routing pod (Plan 6) does not exist yet; until it does, treat this skill as Mode 1 only. The discipline does not change between modes — only the model behind the call. diff --git a/skills/trainer/SKILL.md b/skills/trainer/SKILL.md index b2e6bdc..f50e3a4 100644 --- a/skills/trainer/SKILL.md +++ b/skills/trainer/SKILL.md @@ -243,11 +243,7 @@ treats `pass` as success, `fail` as failure, `skip` as neither. - `fail` — the phase's intended outcome was NOT reached. - `skip` — phase was skipped intentionally (e.g. no candidates passed the gate, write skipped). -**Why this matters:** the routing pod (Plan 6) reads pass-rate to decide whether to route a future call to a local model. If your skill never logs, the routing pod sees no data. - -## Mode 2 Routing Note - -Trainer is the same shape as `session-retrospective` — long-context reading, mechanical filtering — and is a Mode 2 routing candidate. Until Plan 6, treat as Mode 1 only. +**Why this matters:** pass-rate is what a future routing decision would be based on — whether a given call can be served by a local model instead of a cloud one. A skill that never logs contributes no evidence either way. ## Cross-References