@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.
- package/LICENSE +21 -0
- package/README.md +494 -0
- package/canon/AGENTS.md +28 -0
- package/canon/context/DECISIONS.md +4 -0
- package/canon/context/KNOWLEDGE.md +4 -0
- package/canon/context/PROJECT.md +15 -0
- package/canon/loop/loop-spec.md +30 -0
- package/canon/loop/prd.schema.md +14 -0
- package/canon/manifest.yaml +47 -0
- package/canon/policy/gates.md +7 -0
- package/canon/policy/roles.md +9 -0
- package/canon/skills/ATTRIBUTION.md +71 -0
- package/canon/skills/authoring-prd/SKILL.md +44 -0
- package/canon/skills/brainstorming/SKILL.md +164 -0
- package/canon/skills/dispatching-parallel-agents/SKILL.md +182 -0
- package/canon/skills/document-release/SKILL.md +297 -0
- package/canon/skills/executing-plans/SKILL.md +70 -0
- package/canon/skills/finishing-a-development-branch/SKILL.md +200 -0
- package/canon/skills/health/SKILL.md +177 -0
- package/canon/skills/maintaining-context/SKILL.md +34 -0
- package/canon/skills/minimal-code/SKILL.md +21 -0
- package/canon/skills/plan-ceo-review/SKILL.md +541 -0
- package/canon/skills/plan-eng-review/SKILL.md +362 -0
- package/canon/skills/receiving-code-review/SKILL.md +213 -0
- package/canon/skills/requesting-code-review/SKILL.md +105 -0
- package/canon/skills/retro/SKILL.md +397 -0
- package/canon/skills/review/SKILL.md +246 -0
- package/canon/skills/ship/SKILL.md +696 -0
- package/canon/skills/subagent-driven-development/SKILL.md +277 -0
- package/canon/skills/systematic-debugging/SKILL.md +296 -0
- package/canon/skills/tdd/SKILL.md +371 -0
- package/canon/skills/unslop-ui/SKILL.md +34 -0
- package/canon/skills/using-git-worktrees/SKILL.md +218 -0
- package/canon/skills/verification-before-completion/SKILL.md +139 -0
- package/canon/skills/visual-verification/SKILL.md +54 -0
- package/canon/skills/workflow/SKILL.md +18 -0
- package/canon/skills/writing-plans/SKILL.md +152 -0
- package/canon/skills/writing-skills/SKILL.md +655 -0
- package/canon/skills/yoke-retrofit/SKILL.md +18 -0
- package/canon/tools/graphify.md +3 -0
- package/canon/tools/playwright-mcp.md +3 -0
- package/canon/tools/rtk.md +7 -0
- package/canon/tools/serena.md +7 -0
- package/dist/canon/frontmatter.js +10 -0
- package/dist/canon/manifest.js +26 -0
- package/dist/canon/validate.js +73 -0
- package/dist/cli.js +244 -0
- package/dist/context/command.js +33 -0
- package/dist/context/context.js +57 -0
- package/dist/loop/cleanup.js +42 -0
- package/dist/loop/gates.js +12 -0
- package/dist/loop/git.js +25 -0
- package/dist/loop/lock.js +45 -0
- package/dist/loop/loop.js +190 -0
- package/dist/loop/prd.js +29 -0
- package/dist/loop/reporter.js +91 -0
- package/dist/loop/run-command.js +134 -0
- package/dist/loop/runner.js +157 -0
- package/dist/loop/verify.js +38 -0
- package/dist/loop/watchdog.js +86 -0
- package/dist/new/command.js +53 -0
- package/dist/prd/command.js +129 -0
- package/dist/retrofit/apply.js +54 -0
- package/dist/retrofit/canon-dir.js +22 -0
- package/dist/retrofit/command.js +37 -0
- package/dist/retrofit/config.js +53 -0
- package/dist/retrofit/context-actions.js +21 -0
- package/dist/retrofit/detect.js +17 -0
- package/dist/retrofit/gitignore.js +26 -0
- package/dist/retrofit/gstack.js +19 -0
- package/dist/retrofit/merge-json.js +38 -0
- package/dist/retrofit/plan.js +29 -0
- package/dist/retrofit/planners/claude.js +67 -0
- package/dist/retrofit/planners/codex.js +36 -0
- package/dist/retrofit/planners/gemini.js +54 -0
- package/dist/retrofit/report.js +14 -0
- package/dist/retrofit/tools.js +23 -0
- package/dist/retrofit/wsl.js +15 -0
- package/dist/review/command.js +43 -0
- package/dist/scan/design.js +79 -0
- package/dist/smoke/command.js +141 -0
- 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`.
|