mirror of
https://github.com/duthaho/claudekit.git
synced 2026-07-24 05:31:01 +03:00
feat: effort-scaled discipline — Trivial/Small/Standard tiers across the design-phase spine (#6)
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user