From 9e24f1d5118a6ea7b52e4f04f90ff3ddd156d069 Mon Sep 17 00:00:00 2001 From: duthaho Date: Wed, 22 Jul 2026 04:55:38 +0000 Subject: [PATCH] feat: explicit effort-tier model across the design-phase spine Add a Trivial/Small/Standard tier model so the design ceremony scales to the change while the evidence gate never does. README gains a canonical 'Sizing the work' table + the non-negotiable rule (verification-gate and code-review-loop always run); shape-spec gets a Step 0 sizing gate; write-plan and plan-review state which tier they belong to. --- README.md | 14 +++++++++++++- skills/plan-review/SKILL.md | 8 +++++++- skills/shape-spec/SKILL.md | 25 +++++++++++++++++++++++++ skills/write-plan/SKILL.md | 12 ++++++++++-- 4 files changed, 55 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 09bc040..eee5c3f 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,18 @@ Every claudekit skill has 8 required sections: Pick the chain that matches your task. Each one ends at a real stopping point — not every project needs every step. +### Sizing the work + +The chains below show the *full* discipline. Scale it to the change — the ceremony is negotiable, the evidence is not. Size the change first, then run only what the tier earns: + +| Tier | What it is | Design ceremony | Evidence (never scales) | +|---|---|---|---| +| **Trivial** | One-line / single-file / describable in one sentence (typo, config value, rename) | Skip `shape-spec`, `write-plan`, `plan-review` | `verification-gate`, then `code-review-loop` on the diff | +| **Small** | One focused change, ≤ ~3 files, design obvious | Skip `shape-spec` and `plan-review`; a lightweight inline plan is enough | `verification-gate` → `code-review-loop` | +| **Standard** | Multi-file, multi-session, or real design decisions | Full chain: `shape-spec` → `write-plan` → `plan-review` | `verification-gate` → `code-review-loop` | + +**The one rule that never scales:** `verification-gate` always runs, and `code-review-loop` runs on any diff you ship — on a typo as much as a rewrite. Ceremony scales to the change; **evidence does not scale to zero.** A skipped gate is how "trust me" comes back, which is the exact failure claudekit exists to prevent. When you're genuinely unsure which tier a change is, pick the smaller one and say so — the plan contract catches scope growth and upgrades the tier if the work turns out bigger. + ### New feature *"There's a request. No code yet."* @@ -156,7 +168,7 @@ For library/plugin authors before tagging. The audit catches stale deps and unac --- -In practice, devs skip steps for trivial work. The chains show the full discipline; use what the task earns. +In practice, devs skip steps for trivial work — so scale the chain deliberately, per **Sizing the work** above, rather than silently. The chains show the full discipline; the tier tells you how much of it this change earns — but the evidence gate is never the part you skip. ## Development diff --git a/skills/plan-review/SKILL.md b/skills/plan-review/SKILL.md index 75e88f8..cf2093a 100644 --- a/skills/plan-review/SKILL.md +++ b/skills/plan-review/SKILL.md @@ -35,12 +35,18 @@ between `write-plan` and implementation. ## When NOT to Use -- The plan is for a single-file, single-author change (use code review instead) +- The change is **Trivial** or **Small** (see README "Sizing the work") — plan-review is a Standard-tier step; smaller changes go straight to implementation and `code-review-loop` - A previous plan-review already passed and the plan hasn't changed since - You don't have a written plan yet (use `write-plan` first) ## Process +**Effort tier:** plan-review is a **Standard**-tier gate — it earns its cost when a +plan carries real design decisions across multiple files. **Trivial** and **Small** +changes skip it; their safety net is `verification-gate` plus `code-review-loop` on +the diff, which never skip regardless of tier. Reviewing a one-task plan is the kind +of ceremony that teaches people to route around the gates that matter. + ### Step 1: Locate and read the plan **Goal:** Confirm the plan file exists and meets the minimum bar to be reviewed. diff --git a/skills/shape-spec/SKILL.md b/skills/shape-spec/SKILL.md index 6742036..daf6bc3 100644 --- a/skills/shape-spec/SKILL.md +++ b/skills/shape-spec/SKILL.md @@ -42,6 +42,31 @@ is written. ## Process +### Step 0: Size the change + +**Goal:** Scale the ceremony to the change before spending it. A full spec on a +one-line fix trains people to skip the whole discipline; no spec on a multi-module +change is how the missing constraint ships. + +**Actions:** + +1. Classify the change (when unsure between two tiers, pick the smaller and say so + — the plan contract upgrades it later if the work grows): + - **Trivial** — one-line / single-file / describable in one sentence. **Stop + here — no spec.** Make the change, then go straight to `verification-gate` + and `code-review-loop`. + - **Small** — one focused change, ≤ ~3 files, design obvious. **Skip the spec** + and hand off to `write-plan` for a lightweight inline plan; `plan-review` is + optional at this tier. + - **Standard** — multi-file, multi-session, or real design decisions. Continue + to Step 1 and write the full spec. +2. Whatever the tier, the evidence never scales to zero: `verification-gate` runs + and `code-review-loop` reviews any shipped diff. Ceremony is what scales, not + the gate. (Full tier table: README "Sizing the work".) + +**Output:** The chosen tier, stated out loud, and — for Trivial/Small — the handoff +to the right next step instead of a spec. + ### Step 1: One-line summary **Goal:** Force the spec into a single sentence before any further work. diff --git a/skills/write-plan/SKILL.md b/skills/write-plan/SKILL.md index 7236669..0d73fee 100644 --- a/skills/write-plan/SKILL.md +++ b/skills/write-plan/SKILL.md @@ -35,12 +35,20 @@ before code or `plan-review`. ## When NOT to Use -- The change is single-file and you'll finish it in 30 minutes +- The change is **Trivial** (one-line / single-file / describable in one sentence) — skip planning, make the change, run `verification-gate` - A plan exists; you should be running `plan-review` against it, not rewriting it -- You don't have a spec yet — go to `shape-spec` first +- You don't have a spec yet and the change is **Standard** — go to `shape-spec` first ## Process +**Effort tier:** planning is for **Small** and **Standard** changes. A **Small** +change (≤ ~3 files, obvious design) needs only a lightweight inline plan — the +task list and per-task acceptance check below, skipping the spec that fed it. A +**Standard** change gets the full plan and then `plan-review`. **Trivial** changes +skip this skill entirely. Either way `verification-gate` and `code-review-loop` +still run — planning scales, the gate does not. (Full tier table: README "Sizing +the work".) + ### Step 1: Confirm the spec is sufficient **Goal:** Avoid planning against a spec that itself is incomplete.