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

Commit 56777d0

Browse files
committed
skills: add anti-rationalization sections to 4 core skills
Add Common Rationalizations (table format), Red Flags (observable symptoms), and Verification (checkbox checklists) sections to: - flow-code-plan - flow-code-work - flow-code-impl-review - flow-code-epic-review Follows the pattern established in flow-code-debug SKILL.md. Task: fn-136-borrow-agent-skills-patterns-anti.3
1 parent d997c7b commit 56777d0

4 files changed

Lines changed: 107 additions & 0 deletions

File tree

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,3 +188,29 @@ Epic review passed. Next:
188188
2) Ship the code: push + create PR
189189
3) Start next epic: `/flow-code:plan <idea>`
190190
```
191+
192+
## Common Rationalizations
193+
194+
| Excuse | Reality |
195+
|--------|---------|
196+
| "All tasks passed, epic must be fine" | Task-level success ≠ epic-level coherence. Integration gaps hide between tasks |
197+
| "Tests pass, ship it" | Tests verify code behavior, not user value. Goal-backward check verifies intent |
198+
| "We already reviewed each task" | Per-task review misses cross-task consistency and architectural drift |
199+
| "The user will catch any issues" | Your job is to catch issues before the user does |
200+
| "Good enough for now" | "Good enough" compounds into technical debt. Ship complete or scope down |
201+
202+
## Red Flags
203+
204+
- All acceptance criteria marked "Yes" but no test evidence provided
205+
- Implementation diverged from epic plan (compare git diff vs spec scope)
206+
- Goal-backward verification skipped or done superficially
207+
- Epic has open required gaps but no justification for proceeding
208+
- No cross-task integration verification performed
209+
210+
## Verification
211+
212+
- [ ] Every acceptance criterion verified with evidence (test output, screenshot, or manual check)
213+
- [ ] Goal-backward verification completed for each criterion
214+
- [ ] No open required gaps in gap registry
215+
- [ ] Epic spec updated if scope changed during implementation
216+
- [ ] Cross-task consistency verified (no conflicting changes between tasks)

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,3 +155,29 @@ If verdict is NEEDS_WORK, loop internally until SHIP:
155155
5. **Repeat** until `<verdict>SHIP</verdict>`
156156

157157
**CRITICAL**: For RP, re-reviews must stay in the SAME chat so reviewer has context. Only use `--new-chat` on the FIRST review.
158+
159+
## Common Rationalizations
160+
161+
| Excuse | Reality |
162+
|--------|---------|
163+
| "Reviewer said fix, so it must be right" | Review feedback needs technical verification too. Reviewers can be wrong |
164+
| "This is just cosmetic" | 3 cosmetic issues often signal a structural problem underneath |
165+
| "3 iterations is overkill for this" | The circuit breaker exists for a reason. If you hit it, the plan was wrong |
166+
| "I already fixed the important ones" | "Important" is defined by severity, not your estimate of effort |
167+
| "The code works, reviewer is being pedantic" | Working code is the minimum bar, not the finish line |
168+
169+
## Red Flags
170+
171+
- Same issue appears across 3+ review iterations (underlying design problem)
172+
- Fix introduces a new Critical finding
173+
- SHIP verdict issued with zero test evidence
174+
- Review only checks code quality but ignores spec compliance
175+
- ≥3 Critical findings in a single review pass
176+
177+
## Verification
178+
179+
- [ ] All Critical findings addressed with specific fixes
180+
- [ ] No fix introduced new Critical or Important issues
181+
- [ ] Tests still pass after all fixes applied
182+
- [ ] Review receipt saved to .flow/reviews/
183+
- [ ] Acceptance criteria verified (not just code quality)

skills/flow-code-plan/SKILL.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,3 +142,31 @@ All plans go into `.flow/`:
142142
**After work completes** (if auto-executed):
143143
- All tasks done → Layer 3 adversarial review runs automatically (Phase 3j)
144144
- Then auto push + draft PR (Phase 5)
145+
146+
## Common Rationalizations
147+
148+
| Excuse | Reality |
149+
|--------|---------|
150+
| "This is obvious, skip scouts" | Scouts find patterns and reuse points you don't know about |
151+
| "Only one task, no DAG needed" | Even single tasks need dependency analysis and acceptance criteria |
152+
| "Requirements are clear, skip interview" | Your understanding ≠ user's intent. A 2-minute check prevents 2-hour rework |
153+
| "This is too small to plan" | Small plans still need acceptance criteria. A 3-line spec is fine |
154+
| "I'll refine the plan during implementation" | Implementation drift is the #1 cause of rework. Plan now |
155+
156+
## Red Flags
157+
158+
- Any task estimated >L size without being split
159+
- Scout returns "Cannot analyze" but planning continues without investigation
160+
- Task title contains "and" (likely two tasks combined)
161+
- No acceptance criteria on any task
162+
- Plan has zero file references from repo-scout
163+
- 7+ tasks in a single epic (possible over-splitting)
164+
165+
## Verification
166+
167+
- [ ] Every task has ≥1 testable acceptance criterion
168+
- [ ] Every task is ≤M size (L tasks split)
169+
- [ ] File refs from repo-scout included in task specs
170+
- [ ] DAG validated (`flowctl validate`)
171+
- [ ] Quick commands section exists in epic spec
172+
- [ ] No task title contains "and" without justification

skills/flow-code-work/SKILL.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,3 +136,30 @@ $FLOWCTL restart <task-id> --force
136136
- Don't leave tasks half-done
137137
- Never use TodoWrite for task tracking
138138
- Never create plan files outside `.flow/`
139+
140+
## Common Rationalizations
141+
142+
| Excuse | Reality |
143+
|--------|---------|
144+
| "Spec is good enough, skip re-anchor" | Specs change during plan-review. Always re-read before implementing |
145+
| "Guard passed, definitely no issues" | Guards may not cover your specific change. Manual verification still needed |
146+
| "Small change, no test needed" | Small changes are the #1 source of regressions |
147+
| "I'll test after all tasks are done" | Cross-task integration bugs are 10x harder to diagnose than per-task bugs |
148+
| "One more attempt will fix it" | 3+ failed attempts = architectural problem. Escalate, don't retry |
149+
150+
## Red Flags
151+
152+
- ≥2 tasks failed in the same wave (systemic issue, stop and investigate)
153+
- Same file needs 3+ fixes across iterations
154+
- Guard passes but manual test reveals broken behavior
155+
- Worker reports "spec unclear" but continues implementing
156+
- >100 lines changed without running any tests
157+
- Wave checkpoint skipped or results not reviewed
158+
159+
## Verification
160+
161+
- [ ] All tasks in epic are done or explicitly skipped
162+
- [ ] Guards pass on final state (`flowctl guard`)
163+
- [ ] Evidence files exist for each completed task
164+
- [ ] No unresolved spec conflicts
165+
- [ ] Wave checkpoints completed for each wave

0 commit comments

Comments
 (0)