docs(skills): drop the Mode 2 routing notes, fix the contributing steps
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
This commit is contained in:
@@ -130,13 +130,48 @@ before `task skills:install`; default is `main` for always-current.
|
||||
|
||||
## Contributing a skill
|
||||
|
||||
1. Add a directory `<short-kebab-name>/`.
|
||||
2. Create `<short-kebab-name>/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/<short-kebab-name>/`.
|
||||
2. Create `skills/<short-kebab-name>/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: <short-kebab-name>
|
||||
surfaces: [claude-code, library] # any of claude-code | library | chat
|
||||
summary: "<one line for the index table>"
|
||||
use_when: "<the trigger, for the index table>"
|
||||
description: <the paragraph the model selects on>
|
||||
---
|
||||
```
|
||||
|
||||
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. |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
+1
-5
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user