mirror of
https://github.com/duthaho/claudekit.git
synced 2026-07-22 12:41:00 +03:00
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:
@@ -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.
|
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
|
### New feature
|
||||||
*"There's a request. No code yet."*
|
*"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
|
## Development
|
||||||
|
|
||||||
|
|||||||
@@ -35,12 +35,18 @@ between `write-plan` and implementation.
|
|||||||
|
|
||||||
## When NOT to Use
|
## 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
|
- 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)
|
- You don't have a written plan yet (use `write-plan` first)
|
||||||
|
|
||||||
## Process
|
## 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
|
### Step 1: Locate and read the plan
|
||||||
|
|
||||||
**Goal:** Confirm the plan file exists and meets the minimum bar to be reviewed.
|
**Goal:** Confirm the plan file exists and meets the minimum bar to be reviewed.
|
||||||
|
|||||||
@@ -42,6 +42,31 @@ is written.
|
|||||||
|
|
||||||
## Process
|
## 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
|
### Step 1: One-line summary
|
||||||
|
|
||||||
**Goal:** Force the spec into a single sentence before any further work.
|
**Goal:** Force the spec into a single sentence before any further work.
|
||||||
|
|||||||
@@ -35,12 +35,20 @@ before code or `plan-review`.
|
|||||||
|
|
||||||
## When NOT to Use
|
## 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
|
- 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
|
## 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
|
### Step 1: Confirm the spec is sufficient
|
||||||
|
|
||||||
**Goal:** Avoid planning against a spec that itself is incomplete.
|
**Goal:** Avoid planning against a spec that itself is incomplete.
|
||||||
|
|||||||
Reference in New Issue
Block a user