fix(retro): persist recommendations so the next retro detects follow-through

/retro produced "3 Things to Improve" but never saved them in its JSON
snapshot, so the next retro could not tell whether last week's
recommendations were acted on. Step 13 now drafts the items before saving
and always writes a `recommendations` array ({category, text}, [] when
empty); Step 12 scores each prior recommendation addressed/partial/open
against this window's commits, files and metrics and renders a
follow-through line, skipping silently for snapshots without the key. The
report format ties the items to the saved array. Global mode is unchanged.

Adopts #1853 (rewritten on current main). Refs #1834.

Co-authored-by: Jayesh Betala <jayesh.betala7@gmail.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
committed 2026-10-08 06:36:28 +00:00
1 parent 8fb37a72c0
commit 7e2a6e6ccd
5 files changed
+72 -6

No files matched your search

+8 -1
View File
@@ -761,11 +761,13 @@ Commits: 32 → 47 ↑47%
Deep sessions: 3 → 5 ↑2
```
**Recommendation follow-through:** If that matching-window snapshot has a `recommendations` key, score each prior recommendation as `addressed`, `partial` or `open` against this window's commits, changed files and metrics, citing the evidence. Render a **Recommendation follow-through** line in the report (for example "2 of 3 prior recommendations addressed"), then one line per item with its verdict. If the snapshot has no `recommendations` key, skip this silently.
**If no prior retros exist:** Skip the comparison section and append: "First retro recorded — run again next week to see trends."
### Step 13: Save Retro History
After computing all metrics (including streak) and loading any prior history for comparison, draft the tweetable summary using the format in Step 14, then save a JSON snapshot. The Step 14 narrative must reuse this exact summary. `streak_days` is the live **team** streak from Step 11 (0 when broken); put the personal streak in `user_streak_days`.
After computing all metrics (including streak) and loading any prior history for comparison, draft the tweetable summary and the "3 Things to Improve" items using the format in Step 14, then save a JSON snapshot. The Step 14 narrative must reuse this exact summary and these exact items. `streak_days` is the live **team** streak from Step 11 (0 when broken); put the personal streak in `user_streak_days`.
```bash
mkdir -p .context/retros
@@ -812,6 +814,9 @@ Use the Write tool to save the JSON file with this schema:
"streak_days": 47,
"user_streak_days": 32,
"tweetable": "Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm",
"recommendations": [
{ "category": "testing", "text": "Stabilize the auth fixture in test/fixtures/ that flakes about 1 run in 4" }
],
"greptile": {
"fixes": 3,
"fps": 1,
@@ -821,6 +826,8 @@ Use the Write tool to save the JSON file with this schema:
}
```
**Always include `recommendations`:** one object per "3 Things to Improve" item, with a one-word lowercase `category` and the item's text verbatim. Write `[]` when there are none; never pad.
**Note:** Only include the `greptile` field if `greptile-history.md` (the path `GREPTILE_HISTORY` printed) exists and has entries within the time window. Only include the `backlog` field if `TODOS.md` exists. Only include the `test_health` field if test files were found (`TEST_FILES_TOTAL` > 0). If any has no data, omit the field entirely.
Include test health data in the JSON when test files exist:
+8 -1
View File
@@ -354,11 +354,13 @@ Commits: 32 → 47 ↑47%
Deep sessions: 3 → 5 ↑2
```
**Recommendation follow-through:** If that matching-window snapshot has a `recommendations` key, score each prior recommendation as `addressed`, `partial` or `open` against this window's commits, changed files and metrics, citing the evidence. Render a **Recommendation follow-through** line in the report (for example "2 of 3 prior recommendations addressed"), then one line per item with its verdict. If the snapshot has no `recommendations` key, skip this silently.
**If no prior retros exist:** Skip the comparison section and append: "First retro recorded — run again next week to see trends."
### Step 13: Save Retro History
After computing all metrics (including streak) and loading any prior history for comparison, draft the tweetable summary using the format in Step 14, then save a JSON snapshot. The Step 14 narrative must reuse this exact summary. `streak_days` is the live **team** streak from Step 11 (0 when broken); put the personal streak in `user_streak_days`.
After computing all metrics (including streak) and loading any prior history for comparison, draft the tweetable summary and the "3 Things to Improve" items using the format in Step 14, then save a JSON snapshot. The Step 14 narrative must reuse this exact summary and these exact items. `streak_days` is the live **team** streak from Step 11 (0 when broken); put the personal streak in `user_streak_days`.
```bash
mkdir -p .context/retros
@@ -405,6 +407,9 @@ Use the Write tool to save the JSON file with this schema:
"streak_days": 47,
"user_streak_days": 32,
"tweetable": "Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm",
"recommendations": [
{ "category": "testing", "text": "Stabilize the auth fixture in test/fixtures/ that flakes about 1 run in 4" }
],
"greptile": {
"fixes": 3,
"fps": 1,
@@ -414,6 +419,8 @@ Use the Write tool to save the JSON file with this schema:
}
```
**Always include `recommendations`:** one object per "3 Things to Improve" item, with a one-word lowercase `category` and the item's text verbatim. Write `[]` when there are none; never pad.
**Note:** Only include the `greptile` field if `greptile-history.md` (the path `GREPTILE_HISTORY` printed) exists and has entries within the time window. Only include the `backlog` field if `TODOS.md` exists. Only include the `test_health` field if test files were found (`TEST_FILES_TOTAL` > 0). If any has no data, omit the field entirely.
Include test health data in the JSON when test files exist:
+2 -2
View File
@@ -15,7 +15,7 @@ Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 1
(from Step 2)
### Trends vs Last Retro
(from Step 12, loaded before save — skip if no matching history; in `compare` mode use **Current vs Prior Period** from the computed prior window even on the first run)
(from Step 12, loaded before save — skip if no matching history; in `compare` mode use **Current vs Prior Period** from the computed prior window even on the first run). Include the Recommendation follow-through line when Step 12 produced one.
### Time & Session Patterns
(from Steps 3-4)
@@ -118,7 +118,7 @@ Identify the 3 highest-impact things shipped in the window across the whole team
- Why it matters (product/architecture impact)
### 3 Things to Improve
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..." These are the items saved as `recommendations` in the Step 13 snapshot, which the next retro scores for follow-through, so name a concrete file, script or check in each.
### 3 Habits for Next Week
Small, practical, realistic. Each must be something that takes <5 minutes to adopt. At least one should be team-oriented (e.g., "review each other's PRs same-day").
+2 -2
View File
@@ -13,7 +13,7 @@ Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 1
(from Step 2)
### Trends vs Last Retro
(from Step 12, loaded before save — skip if no matching history; in `compare` mode use **Current vs Prior Period** from the computed prior window even on the first run)
(from Step 12, loaded before save — skip if no matching history; in `compare` mode use **Current vs Prior Period** from the computed prior window even on the first run). Include the Recommendation follow-through line when Step 12 produced one.
### Time & Session Patterns
(from Steps 3-4)
@@ -116,7 +116,7 @@ Identify the 3 highest-impact things shipped in the window across the whole team
- Why it matters (product/architecture impact)
### 3 Things to Improve
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..." These are the items saved as `recommendations` in the Step 13 snapshot, which the next retro scores for follow-through, so name a concrete file, script or check in each.
### 3 Habits for Next Week
Small, practical, realistic. Each must be something that takes <5 minutes to adopt. At least one should be team-oriented (e.g., "review each other's PRs same-day").
@@ -0,0 +1,52 @@
/**
* Regression tests for #1834: /retro wrote "3 Things to Improve" as prose only,
* so the next retro could not tell whether last week's recommendations were
* acted on. The Step 13 snapshot now saves them and Step 12 scores them.
*/
import { describe, expect, test } from "bun:test";
import * as fs from "node:fs";
import * as path from "node:path";
const ROOT = path.resolve(import.meta.dir, "..");
const SKILL = fs.readFileSync(path.join(ROOT, "retro", "SKILL.md"), "utf-8");
const REPORT = fs.readFileSync(path.join(ROOT, "retro", "sections", "report-format.md"), "utf-8");
function step(heading: string, next: string): string {
const start = SKILL.indexOf(heading);
expect(start).toBeGreaterThanOrEqual(0);
const end = SKILL.indexOf(next, start + heading.length);
expect(end).toBeGreaterThan(start);
return SKILL.slice(start, end);
}
describe("#1834 retro persists recommendations and detects follow-through", () => {
const step12 = step("### Step 12: Load History & Compare", "### Step 13:");
const step13 = step("### Step 13: Save Retro History", "### Step 14:");
test("Step 13 schema always saves the 3 Things to Improve as recommendations", () => {
const schema = step13.match(/```json\n(\{[\s\S]*?\n\})\n```/)?.[1] ?? "";
const parsed = JSON.parse(schema);
expect(Array.isArray(parsed.recommendations)).toBe(true);
expect(Object.keys(parsed.recommendations[0]).sort()).toEqual(["category", "text"]);
expect(step13).toContain("**Always include `recommendations`:**");
expect(step13).toContain("Write `[]` when there are none");
expect(step13).toContain('draft the tweetable summary and the "3 Things to Improve" items');
});
test("Step 12 scores prior recommendations and skips older snapshots silently", () => {
expect(step12).toContain("**Recommendation follow-through:**");
expect(step12).toMatch(/`addressed`, `partial` or `open`/);
expect(step12).toContain("2 of 3 prior recommendations addressed");
expect(step12).toContain("If the snapshot has no `recommendations` key, skip this silently.");
});
test("report format ties the 3 Things to Improve to the saved items", () => {
const improve = REPORT.slice(REPORT.indexOf("### 3 Things to Improve"), REPORT.indexOf("### 3 Habits for Next Week"));
expect(improve).toContain("saved as `recommendations` in the Step 13 snapshot");
expect(REPORT).toContain("Include the Recommendation follow-through line when Step 12 produced one.");
});
test("global mode snapshot is unchanged", () => {
expect(step("## Global Retrospective Mode", "## Compare Mode")).not.toContain("recommendations");
});
});