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
+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.