fix: align Small-tier plan-review rule and changelog wording

Resolve two consistency nits from review: shape-spec said plan-review was
'optional' for Small while the README canonical table says skip it (align
to skip); and the changelog now describes both misuse directions the new
rationalizations guard against, not just gate-skipping.

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Effort-scaled discipline across the design-phase spine — a named
+  Trivial/Small/Standard tier model so ceremony scales to the change while the
+  evidence gate never does. README gains a canonical "Sizing the work" table and
+  the non-negotiable rule (`verification-gate` and `code-review-loop` always run,
+  any tier); `shape-spec` gains a `Step 0: Size the change` routing gate;
+  `write-plan` and `plan-review` declare which tier they belong to; each of the
+  three carries a new rationalization against misusing the tier model — skipping
+  the evidence gate under an "it's trivial" excuse, or over-applying full ceremony
+  to a one-liner
+
 ### Added
 
 - `detect-secrets` hook — blocks Write/Edit content containing secret-looking

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
 

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.
@@ -150,6 +156,7 @@ blockers.
 | "I'll skip the blockers I disagree with — they don't apply here." | Sometimes reviewers really are wrong, and an author's domain knowledge can override review. | Skipping a blocker silently is how plan reviews become advisory. The discipline is: skip is fine, but the rationale gets written down in the review artifact. If you can't write a one-line rationale, you don't disagree, you're rationalizing. | Apply Step 4's rule: every skipped blocker gets a one-line rationale. The rationale is the receipt for your choice. Reviewers reading the plan downstream will see the skip and the reason, not just the absence. |
 | "I'll fix the plan in my head and not bother editing the file." | Mental updates feel faster than file edits. | The plan you implement against is the plan in the file, not the one in your head. The mental version drifts during the days between review and implementation. The teammate who picks up a task sees the unfixed version and implements the unfixed plan. | Edit the file. Use the Edit tool, not "I'll rewrite it cleanly." Each change is small; the cumulative edit takes minutes. |
 | "I'll re-read the plan after applying fixes — but I'm sure it's consistent." | After 5 surgical edits, "I'm sure it's still consistent" is a comfortable belief. | Surgical edits drift. A fix that retitles task 4 may leave a `Blocked by: Task 4` reference dangling somewhere. A fix that splits a task into two may leave the numbering inconsistent. The drift is invisible to the author but obvious on a fresh read. | After Step 5's edits are applied, re-read the plan top to bottom. Catch the dangling references before the implementer does. |
+| "This is Small so it skips plan-review — so it can skip the verification gate too." | The tier model does say Small changes skip plan-review, so extending the logic feels consistent. | It isn't consistent — it conflates ceremony with evidence. Skipping plan-review on a Small change is the tier model working as designed; skipping `verification-gate`/`code-review-loop` is the tier model being used as an excuse to ship unverified. Those two gates never scale by tier, precisely because "it was only small" is the story told after every small change that broke production. | Skip plan-review for Trivial/Small — that's correct — but still run `verification-gate` and get `code-review-loop` on the diff. The gate is the one thing a smaller tier never buys you out of. |
 
 ## Evidence Requirements
 

skills/shape-spec/SKILL.md

@@ -42,6 +42,30 @@ 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 plan-review**; hand off to `write-plan` for a lightweight inline plan.
+   - **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.
@@ -141,6 +165,7 @@ note.
 | "We'll add tests later — acceptance criteria can be vague for now." | Acceptance criteria do mature during implementation. Premature specificity can lock in the wrong thing. | Vague acceptance criteria are how "done" becomes negotiable. Without falsifiable criteria, the engineer who finishes and the reviewer who signs off are negotiating on vibes. The work merges, then someone discovers the missing case in production. | Write at least one falsifiable criterion per goal. If you can't, the goal isn't concrete enough — fix the goal first. |
 | "There are no open questions, this one's clear." | Sometimes a spec really is well-understood. Forcing questions for show is performative. | "No open questions" almost always means "I haven't looked hard enough." Every spec interacts with infra, data, or upstream/downstream systems, each of which has assumptions you haven't audited. The questions are real; you just haven't asked them. | List at least one open question. If you can't find a real one, write down the assumption you're least sure of as a question — "Are we sure component X behaves this way under load?" That assumption is your weakest link. |
 | "We don't need a constraints section for an internal tool." | Internal tools are real, and the formality of constraint-writing fits external APIs better. | Internal tools have constraints too — runtime version, deploy environment, who can call them, data sensitivity. Skipping the section because "internal" is how the internal tool ends up using a deprecated runtime, a soon-to-be-removed library, or storing data the org isn't allowed to log. | Write the constraints section. For internal tools, "Compatibility: must run on the org's standard Python 3.11 runtime" and "Security: must not log PII" are short and they matter. |
+| "It's a one-liner, so I'll skip the spec — and the verification while I'm at it." | Small changes shouldn't drag a spec-and-plan process behind them; that much is right (Step 0 says so). | The first half is correct and the second half is the trap. Effort scaling is a licence to skip *ceremony* — shape-spec, write-plan, plan-review — not *evidence*. "I skipped the spec, so I'll skip the gate too" is how a Trivial typo ships an untested regression, and it's precisely the "trust me, it works" failure the whole toolkit exists to refuse. | Size the change at Step 0 and skip the ceremony the tier doesn't earn — but run `verification-gate` and `code-review-loop` on the diff no matter how small. Evidence never scales to zero. |
 
 ## Evidence Requirements
 

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.
@@ -148,6 +156,7 @@ knows when to move on and the reviewer knows what to look for.
 | "Acceptance is just 'tests pass.'" | TDD culture tells us tests are the contract. | "Tests pass" is necessary, not sufficient. A task can pass tests and still not satisfy the acceptance criterion if the test was scoped wrong, the wrong cases were covered, or the criterion includes something tests don't catch (a UX flow, a perf budget, a doc update). The acceptance line names *which* observable thing proves the task done. | Write the acceptance line as: "Test X passes AND when I run Y in dev, I see Z." Most tasks need both halves. |
 | "I don't need parallelism notes — we'll figure it out as we go." | Most plans are executed sequentially anyway. Annotating parallelism for a one-person project is overhead. | The annotation is cheap; the absence is expensive when a second person joins or the same engineer wants to pick the next task while CI runs the previous one. The cases where parallelism notes don't matter are also the cases where adding them takes 60 seconds. | If the plan has more than 5 tasks, add the parallelism notes. They're not for the first author; they're for whoever is on the project a week from now. |
 | "Rollback is the deploy team's problem." | Some risks really do live in the deploy step, owned by SRE / ops. | "Their problem" assumes someone else has the context to write the rollback. They don't. The engineer who wrote the migration knows what to undo; SRE can run the rollback but can't author it. The plan owner is the right author of the rollback note. | Write the one-line rollback yourself. If you don't know what it would be, you don't know what risk you're taking. Flag it; don't punt it. |
+| "This change is tiny, but I'll write the full multi-task plan to be safe." | Thoroughness feels like the safe default, and a plan never hurts. | A five-task plan for a one-file change is ceremony that trains you and your reviewers to treat the plan as theater — and theater gets skipped next time, including on the Standard change that needed it. Over-applying the process erodes it as surely as skipping it does. | Size the change (README "Sizing the work"). A **Small** change gets the lightweight inline plan — the task list and per-task acceptance check, nothing more; a **Trivial** one skips planning entirely and goes to `verification-gate`. Save the full plan for Standard work. |
 
 ## Evidence Requirements