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.
This commit is contained in:
duthaho
2026-07-22 04:55:38 +00:00
parent 5ff342ad8f
commit 9e24f1d511
4 changed files with 55 additions and 4 deletions
+13 -1
View File
@@ -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
+7 -1
View File
@@ -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.
+25
View File
@@ -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.
+10 -2
View File
@@ -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.