@hecer/yoke 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +494 -0
  3. package/canon/AGENTS.md +28 -0
  4. package/canon/context/DECISIONS.md +4 -0
  5. package/canon/context/KNOWLEDGE.md +4 -0
  6. package/canon/context/PROJECT.md +15 -0
  7. package/canon/loop/loop-spec.md +30 -0
  8. package/canon/loop/prd.schema.md +14 -0
  9. package/canon/manifest.yaml +47 -0
  10. package/canon/policy/gates.md +7 -0
  11. package/canon/policy/roles.md +9 -0
  12. package/canon/skills/ATTRIBUTION.md +71 -0
  13. package/canon/skills/authoring-prd/SKILL.md +44 -0
  14. package/canon/skills/brainstorming/SKILL.md +164 -0
  15. package/canon/skills/dispatching-parallel-agents/SKILL.md +182 -0
  16. package/canon/skills/document-release/SKILL.md +297 -0
  17. package/canon/skills/executing-plans/SKILL.md +70 -0
  18. package/canon/skills/finishing-a-development-branch/SKILL.md +200 -0
  19. package/canon/skills/health/SKILL.md +177 -0
  20. package/canon/skills/maintaining-context/SKILL.md +34 -0
  21. package/canon/skills/minimal-code/SKILL.md +21 -0
  22. package/canon/skills/plan-ceo-review/SKILL.md +541 -0
  23. package/canon/skills/plan-eng-review/SKILL.md +362 -0
  24. package/canon/skills/receiving-code-review/SKILL.md +213 -0
  25. package/canon/skills/requesting-code-review/SKILL.md +105 -0
  26. package/canon/skills/retro/SKILL.md +397 -0
  27. package/canon/skills/review/SKILL.md +246 -0
  28. package/canon/skills/ship/SKILL.md +696 -0
  29. package/canon/skills/subagent-driven-development/SKILL.md +277 -0
  30. package/canon/skills/systematic-debugging/SKILL.md +296 -0
  31. package/canon/skills/tdd/SKILL.md +371 -0
  32. package/canon/skills/unslop-ui/SKILL.md +34 -0
  33. package/canon/skills/using-git-worktrees/SKILL.md +218 -0
  34. package/canon/skills/verification-before-completion/SKILL.md +139 -0
  35. package/canon/skills/visual-verification/SKILL.md +54 -0
  36. package/canon/skills/workflow/SKILL.md +18 -0
  37. package/canon/skills/writing-plans/SKILL.md +152 -0
  38. package/canon/skills/writing-skills/SKILL.md +655 -0
  39. package/canon/skills/yoke-retrofit/SKILL.md +18 -0
  40. package/canon/tools/graphify.md +3 -0
  41. package/canon/tools/playwright-mcp.md +3 -0
  42. package/canon/tools/rtk.md +7 -0
  43. package/canon/tools/serena.md +7 -0
  44. package/dist/canon/frontmatter.js +10 -0
  45. package/dist/canon/manifest.js +26 -0
  46. package/dist/canon/validate.js +73 -0
  47. package/dist/cli.js +244 -0
  48. package/dist/context/command.js +33 -0
  49. package/dist/context/context.js +57 -0
  50. package/dist/loop/cleanup.js +42 -0
  51. package/dist/loop/gates.js +12 -0
  52. package/dist/loop/git.js +25 -0
  53. package/dist/loop/lock.js +45 -0
  54. package/dist/loop/loop.js +190 -0
  55. package/dist/loop/prd.js +29 -0
  56. package/dist/loop/reporter.js +91 -0
  57. package/dist/loop/run-command.js +134 -0
  58. package/dist/loop/runner.js +157 -0
  59. package/dist/loop/verify.js +38 -0
  60. package/dist/loop/watchdog.js +86 -0
  61. package/dist/new/command.js +53 -0
  62. package/dist/prd/command.js +129 -0
  63. package/dist/retrofit/apply.js +54 -0
  64. package/dist/retrofit/canon-dir.js +22 -0
  65. package/dist/retrofit/command.js +37 -0
  66. package/dist/retrofit/config.js +53 -0
  67. package/dist/retrofit/context-actions.js +21 -0
  68. package/dist/retrofit/detect.js +17 -0
  69. package/dist/retrofit/gitignore.js +26 -0
  70. package/dist/retrofit/gstack.js +19 -0
  71. package/dist/retrofit/merge-json.js +38 -0
  72. package/dist/retrofit/plan.js +29 -0
  73. package/dist/retrofit/planners/claude.js +67 -0
  74. package/dist/retrofit/planners/codex.js +36 -0
  75. package/dist/retrofit/planners/gemini.js +54 -0
  76. package/dist/retrofit/report.js +14 -0
  77. package/dist/retrofit/tools.js +23 -0
  78. package/dist/retrofit/wsl.js +15 -0
  79. package/dist/review/command.js +43 -0
  80. package/dist/scan/design.js +79 -0
  81. package/dist/smoke/command.js +141 -0
  82. package/package.json +61 -0
@@ -0,0 +1,397 @@
1
+ ---
2
+ name: retro
3
+ description: |
4
+ Weekly engineering retrospective. Analyzes commit history, work patterns, and code quality
5
+ metrics for the time window. Team-aware: identifies the user, then analyzes every
6
+ contributor with per-person praise and growth opportunities.
7
+ Use when asked for a "retro", "engineering retrospective", or "weekly summary".
8
+ triggers:
9
+ - retro
10
+ - engineering retrospective
11
+ - weekly retro
12
+ - weekly summary
13
+ ---
14
+
15
+ # Engineering Retrospective
16
+
17
+ You are running the `retro` skill. Generate a comprehensive engineering retrospective analyzing commit history, work patterns, and code quality metrics.
18
+
19
+ ## Arguments
20
+
21
+ - (none) — default: last 7 days
22
+ - `24h` — last 24 hours
23
+ - `14d` — last 14 days
24
+ - `30d` — last 30 days
25
+ - `compare` — compare current window vs prior same-length window
26
+ - `compare 14d` — compare with explicit window
27
+
28
+ ## Instructions
29
+
30
+ Parse the argument to determine the time window. Default to 7 days if no argument given. All times should be reported in the user's **local timezone** (use the system default — do NOT set `TZ`).
31
+
32
+ **Midnight-aligned windows:** For day (`d`) and week (`w`) units, compute an absolute start date at local midnight, not a relative string. For example, if today is 2026-03-18 and the window is 7 days: the start date is 2026-03-11. Use `--since="2026-03-11T00:00:00"` for git log queries — the explicit `T00:00:00` suffix ensures git starts from midnight. For week units, multiply by 7 to get days. For hour (`h`) units, use `--since="N hours ago"`.
33
+
34
+ **Argument validation:** If the argument doesn't match a number followed by `d`, `h`, or `w`, or the word `compare` (optionally followed by a window), show usage and stop:
35
+ ```
36
+ Usage: retro [window | compare]
37
+ retro — last 7 days (default)
38
+ retro 24h — last 24 hours
39
+ retro 14d — last 14 days
40
+ retro 30d — last 30 days
41
+ retro compare — compare this period vs prior period
42
+ retro compare 14d — compare with explicit window
43
+ ```
44
+
45
+ ### Step 1: Gather Raw Data
46
+
47
+ First, fetch origin and identify the current user:
48
+ ```bash
49
+ git fetch origin <default> --quiet
50
+ git config user.name
51
+ git config user.email
52
+ ```
53
+
54
+ The name returned by `git config user.name` is **"you"** — the person reading this retro. All other authors are teammates.
55
+
56
+ Run ALL of these git commands in parallel (they are independent):
57
+
58
+ ```bash
59
+ # 1. All commits in window with timestamps, subject, hash, author, files changed
60
+ git log origin/<default> --since="<window>" --format="%H|%aN|%ae|%ai|%s" --shortstat
61
+
62
+ # 2. Per-commit test vs total LOC breakdown with author
63
+ git log origin/<default> --since="<window>" --format="COMMIT:%H|%aN" --numstat
64
+
65
+ # 3. Commit timestamps for session detection and hourly distribution (with author)
66
+ git log origin/<default> --since="<window>" --format="%at|%aN|%ai|%s" | sort -n
67
+
68
+ # 4. Files most frequently changed (hotspot analysis)
69
+ git log origin/<default> --since="<window>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn
70
+
71
+ # 5. PR/MR numbers from commit messages (GitHub #NNN, GitLab !NNN)
72
+ git log origin/<default> --since="<window>" --format="%s" | grep -oE '[#!][0-9]+' | sort | uniq
73
+
74
+ # 6. Per-author file hotspots (who touches what)
75
+ git log origin/<default> --since="<window>" --format="AUTHOR:%aN" --name-only
76
+
77
+ # 7. Per-author commit counts (quick summary)
78
+ git shortlog origin/<default> --since="<window>" -sn --no-merges
79
+
80
+ # 8. TODOS.md backlog (if available)
81
+ cat TODOS.md 2>/dev/null || true
82
+
83
+ # 9. Test file count
84
+ find . -name '*.test.*' -o -name '*.spec.*' -o -name '*_test.*' -o -name '*_spec.*' 2>/dev/null | grep -v node_modules | wc -l
85
+
86
+ # 10. Regression test commits in window
87
+ git log origin/<default> --since="<window>" --oneline --grep="test:" --grep="regression"
88
+
89
+ # 11. Test files changed in window
90
+ git log origin/<default> --since="<window>" --format="" --name-only | grep -E '\.(test|spec)\.' | sort -u | wc -l
91
+ ```
92
+
93
+ ### Step 2: Compute Metrics
94
+
95
+ Calculate and present these metrics in a summary table:
96
+
97
+ | Metric | Value |
98
+ |--------|-------|
99
+ | **Features shipped** (from CHANGELOG + merged PR titles) | N |
100
+ | Commits to main | N |
101
+ | Weighted commits (commits × avg files-touched, capped at 20 per commit) | N |
102
+ | Contributors | N |
103
+ | PRs merged | N |
104
+ | **Logical SLOC added** (non-blank, non-comment — primary code-volume metric) | N |
105
+ | Raw LOC: insertions | N |
106
+ | Raw LOC: deletions | N |
107
+ | Raw LOC: net | N |
108
+ | Test LOC (insertions) | N |
109
+ | Test LOC ratio | N% |
110
+ | Version range | vX.Y.Z → vX.Y.Z |
111
+ | Active days | N |
112
+ | Detected sessions | N |
113
+ | Avg raw LOC/session-hour | N |
114
+ | Test Health | N total tests · M added this period · K regression tests |
115
+
116
+ **Metric order rationale:** features shipped leads — what users got. Commits and weighted commits reflect intent-to-ship. Logical SLOC added reflects real new functionality. Raw LOC is demoted to context because AI inflates it.
117
+
118
+ Then show a **per-author leaderboard** immediately below:
119
+
120
+ ```
121
+ Contributor Commits +/- Top area
122
+ You (name) 32 +2400/-300 src/services/
123
+ alice 12 +800/-150 app/api/
124
+ bob 3 +120/-40 tests/
125
+ ```
126
+
127
+ Sort by commits descending. The current user (from `git config user.name`) always appears first, labeled "You (name)".
128
+
129
+ **Backlog Health (if TODOS.md exists):** Compute:
130
+ - Total open TODOs (exclude items in `## Completed` section)
131
+ - P0/P1 count (critical/urgent items)
132
+ - P2 count (important items)
133
+ - Items completed this period (items in Completed section with dates within the retro window)
134
+
135
+ Include in the metrics table:
136
+ ```
137
+ | Backlog Health | N open (X P0/P1, Y P2) · Z completed this period |
138
+ ```
139
+
140
+ ### Step 3: Commit Time Distribution
141
+
142
+ Show hourly histogram in local time using bar chart:
143
+
144
+ ```
145
+ Hour Commits
146
+ 00: 4 ████
147
+ 07: 5 █████
148
+ ...
149
+ ```
150
+
151
+ Identify and call out:
152
+ - Peak hours
153
+ - Dead zones
154
+ - Whether pattern is bimodal (morning/evening) or continuous
155
+ - Late-night coding clusters (after 10pm)
156
+
157
+ ### Step 4: Work Session Detection
158
+
159
+ Detect sessions using **45-minute gap** threshold between consecutive commits. For each session report:
160
+ - Start/end time (local timezone)
161
+ - Number of commits
162
+ - Duration in minutes
163
+
164
+ Classify sessions:
165
+ - **Deep sessions** (50+ min)
166
+ - **Medium sessions** (20-50 min)
167
+ - **Micro sessions** (<20 min, typically single-commit fire-and-forget)
168
+
169
+ Calculate:
170
+ - Total active coding time (sum of session durations)
171
+ - Average session length
172
+ - LOC per hour of active time
173
+
174
+ ### Step 5: Commit Type Breakdown
175
+
176
+ Categorize by conventional commit prefix (feat/fix/refactor/test/chore/docs). Show as percentage bar:
177
+
178
+ ```
179
+ feat: 20 (40%) ████████████████████
180
+ fix: 27 (54%) ███████████████████████████
181
+ refactor: 2 ( 4%) ██
182
+ ```
183
+
184
+ Flag if fix ratio exceeds 50% — this signals a "ship fast, fix fast" pattern that may indicate review gaps.
185
+
186
+ ### Step 6: Hotspot Analysis
187
+
188
+ Show top 10 most-changed files. Flag:
189
+ - Files changed 5+ times (churn hotspots)
190
+ - Test files vs production files in the hotspot list
191
+ - VERSION/CHANGELOG frequency (version discipline indicator)
192
+
193
+ ### Step 7: PR Size Distribution
194
+
195
+ From commit diffs, estimate PR sizes and bucket them:
196
+ - **Small** (<100 LOC)
197
+ - **Medium** (100-500 LOC)
198
+ - **Large** (500-1500 LOC)
199
+ - **XL** (1500+ LOC)
200
+
201
+ ### Step 8: Focus Score + Ship of the Week
202
+
203
+ **Focus score:** Calculate the percentage of commits touching the single most-changed top-level directory. Higher score = deeper focused work. Lower score = scattered context-switching. Report as: "Focus score: 62% (src/services/)"
204
+
205
+ **Ship of the week:** Auto-identify the single highest-LOC PR in the window. Highlight it:
206
+ - PR number and title
207
+ - LOC changed
208
+ - Why it matters (infer from commit messages and files touched)
209
+
210
+ ### Step 9: Team Member Analysis
211
+
212
+ For each contributor (including the current user), compute:
213
+
214
+ 1. **Commits and LOC** — total commits, insertions, deletions, net LOC
215
+ 2. **Areas of focus** — which directories/files they touched most (top 3)
216
+ 3. **Commit type mix** — their personal feat/fix/refactor/test breakdown
217
+ 4. **Session patterns** — when they code (their peak hours), session count
218
+ 5. **Test discipline** — their personal test LOC ratio
219
+ 6. **Biggest ship** — their single highest-impact commit or PR in the window
220
+
221
+ **For the current user ("You"):** This section gets the deepest treatment. Include all the detail from the solo retro — session analysis, time patterns, focus score. Frame it in first person: "Your peak hours...", "Your biggest ship..."
222
+
223
+ **For each teammate:** Write 2-3 sentences covering what they worked on and their pattern. Then:
224
+
225
+ - **Praise** (1-2 specific things): Anchor in actual commits. Not "great work" — say exactly what was good.
226
+ - **Opportunity for growth** (1 specific thing): Frame as a leveling-up suggestion, not criticism. Anchor in actual data.
227
+
228
+ **If only one contributor (solo repo):** Skip the team breakdown — the retro is personal.
229
+
230
+ **If there are Co-Authored-By trailers:** Parse `Co-Authored-By:` lines in commit messages. Credit those authors for the commit alongside the primary author. Note AI co-authors (e.g., `noreply@anthropic.com`) but do not include them as team members — instead, track "AI-assisted commits" as a separate metric.
231
+
232
+ ### Step 10: Week-over-Week Trends (if window >= 14d)
233
+
234
+ If the time window is 14 days or more, split into weekly buckets and show trends:
235
+ - Commits per week (total and per-author)
236
+ - LOC per week
237
+ - Test ratio per week
238
+ - Fix ratio per week
239
+ - Session count per week
240
+
241
+ ### Step 11: Streak Tracking
242
+
243
+ Count consecutive days with at least 1 commit to origin/<default>, going back from today.
244
+
245
+ ```bash
246
+ # Team streak: all unique commit dates (local time) — no hard cutoff
247
+ git log origin/<default> --format="%ad" --date=format:"%Y-%m-%d" | sort -u
248
+
249
+ # Personal streak: only the current user's commits
250
+ git log origin/<default> --author="<user_name>" --format="%ad" --date=format:"%Y-%m-%d" | sort -u
251
+ ```
252
+
253
+ Count backward from today — how many consecutive days have at least one commit? Display both:
254
+ - "Team shipping streak: 47 consecutive days"
255
+ - "Your shipping streak: 32 consecutive days"
256
+
257
+ ### Step 12: Load History & Compare
258
+
259
+ Before saving the new snapshot, check for prior retro history:
260
+
261
+ ```bash
262
+ ls -t .context/retros/*.json 2>/dev/null
263
+ ```
264
+
265
+ **If prior retros exist:** Load the most recent one using the Read tool. Calculate deltas for key metrics and include a **Trends vs Last Retro** section:
266
+ ```
267
+ Last Now Delta
268
+ Test ratio: 22% → 41% ↑19pp
269
+ Sessions: 10 → 14 ↑4
270
+ LOC/hour: 200 → 350 ↑75%
271
+ Fix ratio: 54% → 30% ↓24pp (improving)
272
+ ```
273
+
274
+ **If no prior retros exist:** Skip the comparison and append: "First retro recorded — run again next week to see trends."
275
+
276
+ ### Step 13: Save Retro History
277
+
278
+ After computing all metrics, save a JSON snapshot to `.context/retros/`:
279
+
280
+ ```bash
281
+ mkdir -p .context/retros
282
+ # Filename: {today}-{sequence}.json
283
+ ```
284
+
285
+ Use the Write tool to save with this schema:
286
+ ```json
287
+ {
288
+ "date": "2026-03-08",
289
+ "window": "7d",
290
+ "metrics": {
291
+ "commits": 47,
292
+ "contributors": 3,
293
+ "prs_merged": 12,
294
+ "insertions": 3200,
295
+ "deletions": 800,
296
+ "net_loc": 2400,
297
+ "test_loc": 1300,
298
+ "test_ratio": 0.41,
299
+ "active_days": 6,
300
+ "sessions": 14,
301
+ "deep_sessions": 5,
302
+ "avg_session_minutes": 42,
303
+ "loc_per_session_hour": 350,
304
+ "feat_pct": 0.40,
305
+ "fix_pct": 0.30,
306
+ "peak_hour": 22,
307
+ "ai_assisted_commits": 32
308
+ },
309
+ "authors": {
310
+ "Alice": { "commits": 32, "insertions": 2400, "deletions": 300, "test_ratio": 0.41, "top_area": "src/" }
311
+ },
312
+ "version_range": ["1.16.0", "1.16.1"],
313
+ "streak_days": 47,
314
+ "tweetable": "Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm"
315
+ }
316
+ ```
317
+
318
+ Only include `backlog` if TODOS.md exists. Only include `test_health` if test files were found.
319
+
320
+ ### Step 14: Write the Narrative
321
+
322
+ Structure the output as:
323
+
324
+ ---
325
+
326
+ **Tweetable summary** (first line, before everything else):
327
+ ```
328
+ Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d
329
+ ```
330
+
331
+ ## Engineering Retro: [date range]
332
+
333
+ ### Summary Table
334
+ (from Step 2)
335
+
336
+ ### Trends vs Last Retro
337
+ (from Step 12, if prior retros exist — skip if first retro)
338
+
339
+ ### Time & Session Patterns
340
+ (from Steps 3-4)
341
+
342
+ Narrative interpreting what the team-wide patterns mean:
343
+ - When the most productive hours are and what drives them
344
+ - Whether sessions are getting longer or shorter over time
345
+ - Estimated hours per day of active coding (team aggregate)
346
+
347
+ ### Shipping Velocity
348
+ (from Steps 5-7)
349
+
350
+ Narrative covering:
351
+ - Commit type mix and what it reveals
352
+ - PR size distribution and what it reveals about shipping cadence
353
+ - Fix-chain detection (sequences of fix commits on the same subsystem)
354
+
355
+ ### Code Quality Signals
356
+ - Test LOC ratio trend
357
+ - Hotspot analysis (are the same files churning?)
358
+
359
+ ### Test Health
360
+ - Total test files: N (from command 9)
361
+ - Tests added this period: M (from command 11)
362
+ - Regression test commits: commits matching test: or regression patterns
363
+ - If test ratio < 20%: flag as growth area — "100% test coverage is the goal. Tests make coding safe."
364
+
365
+ ### Focus & Highlights
366
+ (from Step 8)
367
+ - Focus score with interpretation
368
+ - Ship of the week callout
369
+
370
+ ### Your Week (personal deep-dive)
371
+ (from Step 9, for the current user only)
372
+
373
+ This is the section the user cares most about. Include:
374
+ - Their personal commit count, LOC, test ratio
375
+ - Their session patterns and peak hours
376
+ - Their focus areas
377
+ - Their biggest ship
378
+ - **What you did well** (2-3 specific things anchored in commits)
379
+ - **Where to level up** (1-2 specific, actionable suggestions)
380
+
381
+ ### Team Breakdown
382
+ (from Step 9, for each teammate — skip if solo repo)
383
+
384
+ ### Top 3 Team Wins
385
+ Identify the 3 highest-impact things shipped in the window across the whole team. For each:
386
+ - What it was
387
+ - Who shipped it
388
+ - Why it matters (product/architecture impact)
389
+
390
+ ### 3 Things to Improve
391
+ Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."
392
+
393
+ ### 3 Habits for Next Week
394
+ Small, practical, realistic. Each must be something that takes <5 minutes to adopt. At least one should be team-oriented.
395
+
396
+ ### Week-over-Week Trends
397
+ (if applicable, from Step 10)
@@ -0,0 +1,246 @@
1
+ ---
2
+ name: review
3
+ description: |
4
+ Pre-merge code review — the single canonical review of a change before it lands. Covers BOTH
5
+ diff safety/structure (SQL safety, LLM trust-boundary violations, conditional side effects)
6
+ AND engineering quality (architecture fit, edge cases, test coverage, performance). Use when
7
+ asked to "review this PR", "code review", "pre-landing review", "check my diff", or before
8
+ merging. (For plan-time review use plan-eng-review or plan-ceo-review instead.)
9
+ triggers:
10
+ - review this pr
11
+ - code review
12
+ - check my diff
13
+ - pre-landing review
14
+ ---
15
+
16
+ # Pre-Landing PR Review
17
+
18
+ You are running the `review` workflow. Analyze the current branch's diff against the base branch for structural issues that tests don't catch.
19
+
20
+ ---
21
+
22
+ ## Step 0: Detect platform and base branch
23
+
24
+ Detect the git hosting platform from the remote URL:
25
+
26
+ ```bash
27
+ git remote get-url origin 2>/dev/null
28
+ ```
29
+
30
+ - URL contains "github.com" → platform is **GitHub**
31
+ - URL contains "gitlab" → platform is **GitLab**
32
+ - Otherwise check: `gh auth status 2>/dev/null` → GitHub; `glab auth status 2>/dev/null` → GitLab; neither → unknown
33
+
34
+ Determine the base branch (target of the PR, or the repo's default):
35
+
36
+ - GitHub: `gh pr view --json baseRefName -q .baseRefName` or `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`
37
+ - GitLab: `glab mr view -F json 2>/dev/null` → extract `target_branch` or `default_branch`
38
+ - Fallback: `git symbolic-ref refs/remotes/origin/HEAD`, then `origin/main`, then `origin/master`, then `main`
39
+
40
+ Print the detected base branch. Use it as `<base>` in all subsequent commands.
41
+
42
+ ---
43
+
44
+ ## Step 1: Check branch
45
+
46
+ 1. Run `git branch --show-current`.
47
+ 2. If on the base branch: output **"Nothing to review — you're on the base branch or have no changes against it."** and stop.
48
+ 3. Run `git fetch origin <base> --quiet && git diff origin/<base> --stat`. If no diff, output the same message and stop.
49
+
50
+ ---
51
+
52
+ ## Step 1.5: Scope Drift Detection
53
+
54
+ Check whether the diff matches what was requested.
55
+
56
+ 1. Read `TODOS.md` (if it exists). Read PR description (`gh pr view --json body --jq .body 2>/dev/null || true`). Read commit messages (`git log origin/<base>..HEAD --oneline`).
57
+ 2. Identify the **stated intent** — what was this branch supposed to accomplish?
58
+ 3. Run `git diff origin/<base>...HEAD --stat` and compare against the stated intent.
59
+
60
+ Evaluate for:
61
+ - **SCOPE CREEP** — files changed that are unrelated to stated intent; "while I was in there" changes
62
+ - **MISSING REQUIREMENTS** — requirements from TODOS.md/PR description not in the diff; partial implementations
63
+
64
+ Output (before the main review begins):
65
+ ```
66
+ Scope Check: [CLEAN / DRIFT DETECTED / REQUIREMENTS MISSING]
67
+ Intent: <1-line summary of what was requested>
68
+ Delivered: <1-line summary of what the diff actually does>
69
+ [If drift: list each out-of-scope change]
70
+ [If missing: list each unaddressed requirement]
71
+ ```
72
+
73
+ This is **INFORMATIONAL** — does not block the review.
74
+
75
+ ---
76
+
77
+ ## Step 1.6: Plan Completion Audit (optional)
78
+
79
+ Check if there is a plan file referenced in the conversation context or a recent `.md` file in common plan locations (e.g., `~/.claude/plans/`, `.claude/plans/`). If found and relevant to the current branch:
80
+
81
+ Extract actionable items (checkboxes, numbered steps, imperative statements, file-level specs, test requirements). Cross-reference each item against the diff:
82
+ - **DONE** — clear evidence in diff
83
+ - **PARTIAL** — some work started but incomplete
84
+ - **NOT DONE** — no evidence in diff
85
+ - **CHANGED** — goal met by different means
86
+
87
+ For `PARTIAL` or `NOT DONE`, investigate why and rate impact (HIGH/MEDIUM/LOW). For HIGH-impact gaps, use AskUserQuestion:
88
+ - A) Stop and implement missing items
89
+ - B) Ship anyway + create P1 TODOs
90
+ - C) Intentionally dropped
91
+
92
+ Output format:
93
+ ```
94
+ PLAN COMPLETION AUDIT
95
+ ═══════════════════════
96
+ Plan: {path}
97
+ [DONE] Create UserService — src/services/user_service.rb
98
+ [NOT DONE] Add caching layer — no cache-related changes in diff
99
+ COMPLETION: N/M DONE
100
+ ```
101
+
102
+ ---
103
+
104
+ ## Step 2: Read the checklist
105
+
106
+ Read `.claude/skills/review/checklist.md` (if it exists). If the file cannot be read, continue with the built-in checks below.
107
+
108
+ ---
109
+
110
+ ## Step 3: Get the diff
111
+
112
+ ```bash
113
+ git fetch origin <base> --quiet
114
+ git diff origin/<base>
115
+ ```
116
+
117
+ ---
118
+
119
+ ## Step 4: Critical review pass
120
+
121
+ Apply these categories against the diff:
122
+
123
+ **CRITICAL:**
124
+ - **SQL & Data Safety** — string interpolation in queries, missing parameterization, N+1 patterns
125
+ - **Race Conditions & Concurrency** — shared mutable state, missing locks, idempotency violations
126
+ - **LLM Output Trust Boundary** — LLM output used in SQL, shell commands, or DB writes without validation
127
+ - **Shell Injection** — user input passed to shell commands unsanitized
128
+ - **Enum & Value Completeness** — new enum values/types not handled in all switch/case branches
129
+
130
+ For Enum & Value Completeness: use Grep to find all files referencing sibling values, then Read those files. This requires looking outside the diff.
131
+
132
+ **INFORMATIONAL:**
133
+ - Async/sync mixing, column/field name safety, LLM prompt issues, type coercion, frontend/view issues, time window safety, completeness gaps, distribution/CI gaps
134
+
135
+ **Finding format:**
136
+ ```
137
+ [SEVERITY] (confidence: N/10) file:line — description
138
+ ```
139
+
140
+ Confidence scale:
141
+ - 9-10: Verified by reading specific code, concrete bug demonstrated
142
+ - 7-8: High confidence pattern match
143
+ - 5-6: Moderate — show with caveat "Medium confidence, verify this is actually an issue"
144
+ - 3-4: Low — include in appendix only
145
+ - 1-2: Speculation — only report if P0
146
+
147
+ ---
148
+
149
+ ## Step 4.5: Adversarial review (always-on)
150
+
151
+ Dispatch an independent subagent via the Agent tool to review the diff with fresh context. Subagent prompt:
152
+
153
+ > "Run `git diff origin/<base>` to get the diff. Think like an attacker and a chaos engineer. Find ways this code will fail in production: edge cases, race conditions, security holes, resource leaks, failure modes, silent data corruption, logic errors, error handling that swallows failures, trust boundary violations. For each finding, classify as FIXABLE (you know how to fix it) or INVESTIGATE (needs human judgment)."
154
+
155
+ Present findings under `ADVERSARIAL REVIEW (subagent):`. FIXABLE findings flow into the Fix-First pipeline. INVESTIGATE findings are informational.
156
+
157
+ ---
158
+
159
+ ## Step 5: Fix-First Review
160
+
161
+ ### 5a: Classify each finding
162
+
163
+ For each finding from Steps 4 and 4.5:
164
+ - **AUTO-FIX** — mechanical, low-risk, single-file changes (dead code, stale comments, obvious formatting)
165
+ - **ASK** — architectural, security-sensitive, ambiguous scope, or user preference
166
+
167
+ ### 5b: Apply AUTO-FIX items
168
+
169
+ Apply each fix directly. For each:
170
+ `[AUTO-FIXED] [file:line] Problem → what you did`
171
+
172
+ ### 5c: Batch-ask about ASK items
173
+
174
+ Present all ASK items in one AskUserQuestion:
175
+ ```
176
+ I auto-fixed N issues. M need your input:
177
+
178
+ 1. [CRITICAL] file:line — description
179
+ Fix: recommended fix
180
+ → A) Fix B) Skip
181
+
182
+ RECOMMENDATION: Fix all — [reason].
183
+ ```
184
+
185
+ ### 5d: Apply approved fixes
186
+
187
+ Apply fixes for items where the user chose "Fix."
188
+
189
+ ---
190
+
191
+ ## Step 5.5: TODOS cross-reference
192
+
193
+ Read `TODOS.md` (if it exists). Cross-reference the PR:
194
+ - Does this PR close any open TODOs? Note: "This PR addresses TODO: <title>"
195
+ - Does this PR create work that should become a TODO? Flag as informational.
196
+
197
+ ---
198
+
199
+ ## Step 5.6: Documentation staleness check
200
+
201
+ For each `.md` file in the repo root: if the code it describes was changed but the doc was NOT updated in this branch, flag as informational:
202
+ "Documentation may be stale: [file] describes [feature] but code changed. Consider running the `document-release` skill."
203
+
204
+ ---
205
+
206
+ ## Completion Status
207
+
208
+ Report one of:
209
+ - **DONE** — All steps completed, no blocking issues.
210
+ - **DONE_WITH_CONCERNS** — Completed with issues the user should know about.
211
+ - **BLOCKED** — Cannot proceed. State what is blocking.
212
+ - **NEEDS_CONTEXT** — Missing information required to continue.
213
+
214
+ ## Important Rules
215
+
216
+ - **Read the FULL diff before commenting.** Do not flag issues already addressed in the diff.
217
+ - **Fix-first, not read-only.** AUTO-FIX items are applied directly; ASK items only after user approval.
218
+ - **Never commit, push, or create PRs** — that is the `ship` skill's job.
219
+ - **Be terse.** One line problem, one line fix. No preamble.
220
+ - **Only flag real problems.** Skip anything that is fine.
221
+
222
+ ## Engineering-manager checklist
223
+
224
+ Beyond the structural/safety scan above, also review the change as an engineering manager would —
225
+ this is the angle the old `eng-review` skill covered, now folded in here so there is one
226
+ pre-merge review:
227
+
228
+ - **Architecture fit & data flow:** does the change follow the project's established patterns and
229
+ data flow, or does it drift? Flag architectural drift.
230
+ - **Edge cases & error paths:** are unhandled inputs, failure modes, and boundary conditions
231
+ covered?
232
+ - **Test coverage:** is the changed behavior covered by tests that verify behavior (not just
233
+ mocks)? Missing or weak tests for changed behavior is a blocking issue.
234
+ - **Performance:** any obvious regressions (N+1, unbounded growth, needless work in hot paths)?
235
+
236
+ Output a pass/block verdict with specific, actionable findings. A reviewer never reviews their
237
+ own implementation (see `policy/roles.md`).
238
+
239
+ ## Interactive cross-model review
240
+
241
+ Outside the loop, run `yoke review` to have a *second* model review your current diff
242
+ before you commit or push. It resolves to the first available of codex → gemini → claude
243
+ (preferring a model other than the one you are driving), reviews the uncommitted working
244
+ tree by default (or `--base=<ref>` for a branch range), and exits non-zero if it finds a
245
+ blocking issue — so it chains as a gate (`... && yoke review`) or a pre-push hook.
246
+ This is the interactive counterpart to the loop's `--review`/`--reviewer`.