Skip to content
This repository was archived by the owner on Apr 11, 2026. It is now read-only.

Commit 3de2d16

Browse files
z23ccclaude
andcommitted
feat: audit and strengthen anti-rationalization tables across all skills
Reviewed 13 skills for Common Rationalizations and Red Flags coverage. 10 skills already met the >=5 rationalizations, >=3 red flags minimum. Added both sections to the 3 skills that were missing them entirely: plan-review (7 rationalizations, 6 red flags), brainstorm (7, 6), and auto-improve (7, 6). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 8ad20e3 commit 3de2d16

3 files changed

Lines changed: 63 additions & 0 deletions

File tree

skills/flow-code-auto-improve/SKILL.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,27 @@ scripts/auto-improve/auto-improve.sh
280280

281281
If `--watch` was passed, add `--watch` flag.
282282

283+
## Common Rationalizations
284+
285+
| Excuse | Reality |
286+
|--------|---------|
287+
| "I know what to improve without analysis" | Intuition-driven improvements miss the highest-impact targets. Analysis finds the hotspots you don't see. |
288+
| "All improvements are equally valuable" | Impact varies by orders of magnitude. Rank by measured impact, not gut feeling. |
289+
| "Experiments are overhead" | Unverified improvements are guesses. A 2-minute before/after measurement proves the change actually helped. |
290+
| "Guard passes, so the change is safe" | Guards catch regressions, not quality improvements. Passing guards means you didn't break anything — not that you improved anything. |
291+
| "Let's improve everything at once" | Batch changes can't be isolated. One improvement per commit lets you revert the one that caused a regression. |
292+
| "The codebase is too messy to measure" | That's exactly why you need baselines. Measurement reveals which mess matters most. |
293+
| "This refactor is obviously better" | "Obviously better" without metrics is opinion. Measure readability, performance, or maintainability to confirm. |
294+
295+
## Red Flags
296+
297+
- Improvement commits with no before/after metrics in the message
298+
- Multiple unrelated improvements in a single commit
299+
- Auto-improve loop running without guard command configured (no safety net)
300+
- program.md unchanged across many iterations (stale focus, diminishing returns)
301+
- Improvements that increase code complexity without measured benefit
302+
- Reverting to fix regressions introduced by "improvements"
303+
283304
## Notes
284305

285306
- First run auto-scaffolds `scripts/auto-improve/`. Subsequent runs reuse existing program.md (preserves user edits).

skills/flow-code-brainstorm/SKILL.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,3 +160,24 @@ Requirements written to .flow/specs/<slug>-requirements.md
160160
161161
Next step: Run /flow-code:plan .flow/specs/<slug>-requirements.md
162162
```
163+
164+
## Common Rationalizations
165+
166+
| Excuse | Reality |
167+
|--------|---------|
168+
| "I already know what to build" | Premature certainty is the most expensive mistake. Brainstorming surfaces assumptions you didn't know you had. |
169+
| "Brainstorming is just talking, not real work" | Brainstorming produces the requirements doc that drives everything downstream. Skip it and you plan against assumptions. |
170+
| "We don't have time to explore alternatives" | Exploring 3 approaches for 15 minutes is cheaper than rebuilding after choosing wrong on day one. |
171+
| "The first idea is usually right" | First ideas are anchored on recent experience. Pressure-testing reveals options that outperform the obvious choice. |
172+
| "Requirements are already in the ticket" | Tickets describe what someone wants, not what should be built. Brainstorming translates desire into actionable constraints. |
173+
| "Let's just start and iterate" | Iteration without direction is wandering. Brainstorming sets the constraints that make iteration productive. |
174+
| "This is too small to brainstorm" | Small scope doesn't mean small risk. A 5-minute pressure test on a "simple" feature often reveals hidden complexity. |
175+
176+
## Red Flags
177+
178+
- Jumping straight to /flow-code:plan without exploring requirements
179+
- Only one approach considered (no alternatives generated or evaluated)
180+
- Requirements doc has zero constraints or non-goals listed
181+
- "Open Questions" section is empty (every problem has unknowns)
182+
- Brainstorm output restates the original request without adding new insight
183+
- User's actual problem never identified (solution proposed without understanding need)

skills/flow-code-plan-review/SKILL.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -200,3 +200,24 @@ $FLOWCTL checkpoint restore --epic <EPIC_ID> --json
200200
```
201201
202202
**CRITICAL**: For RP, re-reviews must stay in the SAME chat so reviewer has context. Only use `--new-chat` on the FIRST review.
203+
204+
## Common Rationalizations
205+
206+
| Excuse | Reality |
207+
|--------|---------|
208+
| "The plan looks reasonable, ship it" | Reasonable-looking plans fail at implementation. Review forces you to find the gaps before code exists. |
209+
| "We already discussed this verbally" | Verbal agreement evaporates. Written review catches assumptions that felt obvious in conversation but aren't. |
210+
| "Reviewer doesn't know our codebase" | External perspective catches blind spots. Codebase familiarity causes pattern blindness — fresh eyes find structural issues. |
211+
| "Review is blocking progress" | Review prevents rework. A 30-minute review saves days of implementing the wrong design. |
212+
| "The spec is too detailed to review" | Over-detailed specs hide weak architecture behind volume. If it's too complex to review, it's too complex to implement. |
213+
| "Minor plan issues, we'll fix during implementation" | Plan issues compound during implementation. A wrong assumption in the spec becomes wrong code in every task. |
214+
| "Just one more iteration and it's perfect" | Diminishing returns are real. Hit the circuit breaker, ship what's good enough, and capture remaining concerns as gaps. |
215+
216+
## Red Flags
217+
218+
- Plan approved without any reviewer reading the actual task specs
219+
- SHIP verdict with zero questions asked (rubber-stamp review)
220+
- Review feedback ignored because "we know better"
221+
- Same structural issue found in implementation that was present in the plan (review missed it)
222+
- Plan-review skipped because "we're behind schedule"
223+
- Reviewer only checked formatting, not technical feasibility

0 commit comments

Comments
 (0)