docs: rationalizations + changelog for effort-tier model

Add one rationalization row to each design-phase skill against using the
tier model as an excuse to skip the evidence gate (verification-gate /
code-review-loop never scale by tier), and record the change in the
changelog.
This commit is contained in:
duthaho
2026-07-22 04:57:29 +00:00
parent 9e24f1d511
commit 81c94aee91
4 changed files with 14 additions and 0 deletions
+1
View File
@@ -156,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