| name | retro |
| description | Use after finishing a feature or at any natural milestone. Dual retrospective analyzing both the harness workflow (tool) and the application code produced (product). Generates concrete improvement proposals. |
| enforcement | advisory |
| phase | ship |
| standalone | true |
| requires | [] |
Purpose
Two-part analysis after each feature: how did the harness perform (Part A), and how healthy is
the code we produced (Part B). Both parts always run together. Findings feed back into memory,
skill improvements, evaluator calibration, and new stories.
Practices
Data Collection
Before analysis, gather:
- Harness:
.pipeline/audit-trail/events.jsonl is the primary source for gate history and
rework cycles (gate verdicts, retries, kickbacks, HALT lifecycle) — read it, not
.pipeline/gates/ files. Also gather .pipeline/task-status.json, git log (reverts, amends),
.memory/gotchas/, .docs/conflicts/.
- If
.pipeline/audit-trail/events.jsonl is missing or empty despite steps having executed
this run, do NOT read that as "no friction occurred" — report INCOMPLETE for the
gate/rework-history portion of the retro (the audit trail failed to capture it) instead of
silently proceeding as if the run was clean.
- Raw
.pipeline/events.jsonl (not the audit-trail subdirectory) remains the source for
retry-escalation history used in Part C (Context Efficiency Retro).
- Application: full feature diff (branch point to HEAD), test suite output,
.docs/stories/ acceptance criteria, tech-context if loaded
Part A: Harness Retro
Only report problems and improvements. If a dimension has no issues, write "No issues." and move on.
A1. Correctness
Report ONLY: bugs that escaped TDD, negative paths that were missed, edge cases found late.
For each escape: what was missed, which gate should have caught it, what story/test pattern
would prevent recurrence.
A2. Gate Quality
Report ONLY: false positives (gates that blocked correct work — wasted rework) and false
negatives (problems that passed all gates). For each: which gate, what triggered/missed it,
specific calibration fix.
A3. Autonomy
Report ONLY: preventable human interventions (skill gap, missing context, bad prompt).
For each: what specific skill/agent/memory change would prevent recurrence.
Do not list necessary interventions (design decisions, policy choices) — those are expected.
Part B: Application Retro
Only report defects, risks, and debt. Do not describe what is correct or well-structured.
B1. Architecture & Code Quality
Report ONLY: god classes, coupling violations, leaky abstractions, methods >15 lines or
3 branches, copy-paste duplication, misleading names, swallowed exceptions, stack-specific
issues (N+1, missing indexes, unsafe migrations).
B2. Test Quality
Report ONLY: missing coverage (acceptance criteria without tests, untested code paths),
fragile tests coupled to internals, assertions testing implementation instead of behavior.
B3. Security, Performance & Debt
Report ONLY: auth gaps, unvalidated inputs, SQL injection risks, unbounded queries, missing
pagination, untracked TODOs, workarounds needing follow-up stories, vulnerable dependencies.
Part C: Context Efficiency Retro
Review token/context consumption for this feature cycle and identify optimization opportunities.
Analyze:
- Which skills or subagent dispatches consumed the most context? (Count dispatches, estimate scope)
- Were there redundant file reads, unnecessary explorations, or overly broad subagent prompts?
- Did any skill load tech-context or memory that wasn't actually referenced in its output?
- Were complexity tiers correctly applied? (Would a different tier have been appropriate?)
- Did the evaluator/domain reviewer dispatches feel proportionate to the feature's complexity?
Propose:
- Specific SKILL.md changes that would reduce context without degrading output
- Subagent prompt refinements (more focused context, fewer files)
- Steps that could be skipped or batched for this feature's complexity tier
- Model downgrades that would have been safe (e.g., Opus → Sonnet for a specific phase)
Output: 2-3 concrete, actionable findings with finding IDs (C-1, C-2, C-3).
Writing Rules
Problems only. No praise.
- If nothing is wrong in a section, write "No issues." — not a paragraph explaining why
everything is fine. Never describe what worked correctly.
- State each finding ONCE. Reference by ID elsewhere: "See H-3."
- One line per finding. Every finding needs: what, where (file:line), severity, proposed fix.
- The retro exists to improve the harness and the code. Anything that doesn't propose a
concrete change is wasted tokens.
Finding IDs: Number findings sequentially across the whole report.
- H-1, H-2, H-3... for harness findings
- A-1, A-2, A-3... for application findings
- C-1, C-2, C-3... for context efficiency findings
Output: Retro Report
Save to .docs/retros/YYYY-MM-DD-<feature-name>.md:
# Retro: [Feature Name]
**Date:** YYYY-MM-DD | **Stats:** N tasks, M rework cycles, K interventions, N tests passing
## Part A: Harness
- **H-1:** [what, where, severity, fix]
**Proposed changes:**
- [ ] H-1: [specific change]
## Part B: Application
- **A-1:** [what, file:line, severity, fix]
**Proposed changes:**
- [ ] A-1: [specific change → new story]
## Part C: Context Efficiency
### Context Efficiency
- **C-1:** [what, where, impact, proposed change]
**Proposed changes:**
- [ ] C-1: [specific SKILL.md change, prompt refinement, or model downgrade]
## Trends
[One line per trend vs. prior retros.]
Feedback Loops
After writing the retro report, take these actions:
Harness findings → Harness improvements: Persist learnings to .memory/ (gotchas, patterns, decisions). Propose skill/agent prompt modifications as diffs; update agents/evaluator.md calibration and skills/stories/SKILL.md negative path categories as needed.
Application findings → New stories: Create stories in .docs/stories/ for debt and fixes; run conflict-check. These become tracked work, not lost "we should fix this" notes.
Trend tracking: Compare against prior retros — intervention count down (good), same gate failures recurring (calibration needed), same application issues recurring (tech-context needs updating). Note trends in the report.
Verification
