/reflect
Structured reflection producing concrete artifacts. Every finding either becomes
a codified artifact or gets explicitly justified as not worth codifying.
Absorbs /calibrate — mid-session harness postmortem is now a mode of reflect.
Modes
| Mode |
Intent |
| distill (default) |
End-of-session retrospective → codified artifacts |
| calibrate |
Mid-session harness postmortem — agent made a wrong decision, fix the harness BEFORE fixing the code |
| tune-repo |
Refresh context artifacts, update AGENTS.md if drift detected |
Workflow: Distill
- Gather evidence — Spawn parallel sub-agents to scan what changed.
One reviews the git diff and recent log (what changed, what areas, what patterns).
Another scans AGENTS.md, CLAUDE.md, and active skills for instructions that
conflict with what we actually did this session — flag stale or wrong guidance.
- Categorize — went well, friction, bugs, missing artifacts, gaps
- Codify — apply hierarchy (highest leverage wins):
Type system > Lint rule > Hook > Test > CI > Skill > AGENTS.md > Memory
- Execute — write the artifacts (hooks, rules, docs)
- Report — what was codified, what was skipped (with justification)
Default: codify. Exception: justify not codifying.
Workflow: Calibrate
When the agent makes a wrong decision mid-session:
The Norman Principle applies here. The agent didn't fail — the harness did.
"I knew better" is not a valid analysis. If the system let the agent make the
error, the system is badly designed. If the system's own instructions induced
the error, it's really badly designed.
- What went wrong? — Describe the incorrect decision
- Why? — Root cause in the harness (missing context, wrong instruction, stale rule)
- Induction check — Did the harness cause the error? Conflicting instructions,
stale context, misleading skill descriptions, missing hooks that would have
prevented it? Induction errors are the highest-priority fixes.
- Fix the harness — Update the source of the problem:
- Wrong AGENTS.md instruction → fix AGENTS.md
- Missing hook → add hook
- Stale skill reference → update skill
- Missing test → add test
- Then fix the code — The code fix should be trivial now
The harness fix is the real deliverable, not the code fix.
Workflow: Tune-Repo
Refresh context artifacts for a target repo. Run proactively or after
noticing drift between docs and code.
- Scan — Read AGENTS.md, CLAUDE.md, and any skill references. Compare
against actual codebase state (do referenced files/functions still exist?).
- Flag drift — List stale entries, broken references, missing sections.
- Check essentials — Does AGENTS.md include:
- After Compaction recovery instruction? (If not, add one.)
- "Plausible ≠ correct" red line? (If not, add one.)
- Build/test/lint commands? (If not, add from package.json/Makefile.)
- Fix — Update stale content. Delete what's wrong. Add what's missing.
- Report — What was updated, what was deleted, what was added.
Codification Hierarchy
When encoding knowledge, always target the highest-leverage mechanism:
| Level |
Mechanism |
Reliability |
| 1 |
Type system |
Compile-time guarantee |
| 2 |
Lint rule |
Blocks on violation |
| 3 |
Hook |
Runs on every tool use |
| 4 |
Test |
Catches regressions |
| 5 |
CI gate |
Blocks merges |
| 6 |
Skill/reference |
Agent reads on demand |
| 7 |
AGENTS.md |
Agent reads at session start |
| 8 |
Memory |
Last resort, least reliable |
Gap Types
When a session reveals something MISSING:
| Gap |
Signal |
Fix |
| missing_skill |
Had to improvise a reusable workflow |
Create skill |
| missing_tool |
No available tool provided capability |
Hook or MCP |
| repeated_failure |
Same error class across sessions |
Lint rule or guardrail |
| wrong_info |
Acted on stale AGENTS.md or reference |
Update source doc |
| permission_friction |
Correct action blocked |
Hook or settings |
Retro Storage
Issue-scoped feedback: {repo}/.groom/retro/<issue>.md
One file per issue. Feeds /groom's planning loop.
Gotchas
- Reflecting without artifacts: If reflect doesn't produce a commit (hook, rule, skill update, AGENTS.md edit), it was a waste.
- Codifying at the wrong level: Writing a CLAUDE.md line when a hook would be more reliable. Use the hierarchy — type system > lint > hook > test > ... > memory.
- Fixing only the code: When calibrate mode triggers, the harness fix IS the deliverable. The code fix should be trivial after.
- Stale context is worse than no context: A wrong instruction in AGENTS.md causes more harm than a gap. When in doubt, delete stale content.
- Over-codifying obvious patterns: If the model handles it natively, don't write a skill for it. Run
/harness eval to check.
1---2name: reflect3description: Session retrospective, learning extraction, harness postmortem, codification. Distill learnings into hooks/rules/skills. Fix the system, not the instance. Use when: "done", "wrap up", "what did we learn", "retro", "reflect", "calibrate", "why did you do that", "fix your instructions". Trigger: /reflect, /retro, /calibrate.4---56# /reflect78Structured reflection producing concrete artifacts. Every finding either becomes9a codified artifact or gets explicitly justified as not worth codifying.1011Absorbs `/calibrate` — mid-session harness postmortem is now a mode of reflect.1213## Modes1415| Mode | Intent |16|------|--------|17| **distill** (default) | End-of-session retrospective → codified artifacts |18| **calibrate** | Mid-session harness postmortem — agent made a wrong decision, fix the harness BEFORE fixing the code |19| **tune-repo** | Refresh context artifacts, update AGENTS.md if drift detected |2021## Workflow: Distill22231. **Gather evidence** — Spawn parallel sub-agents to scan what changed.24 One reviews the git diff and recent log (what changed, what areas, what patterns).25 Another scans AGENTS.md, CLAUDE.md, and active skills for instructions that26 conflict with what we actually did this session — flag stale or wrong guidance.272. **Categorize** — went well, friction, bugs, missing artifacts, gaps283. **Codify** — apply hierarchy (highest leverage wins):29 ```30 Type system > Lint rule > Hook > Test > CI > Skill > AGENTS.md > Memory31 ```324. **Execute** — write the artifacts (hooks, rules, docs)335. **Report** — what was codified, what was skipped (with justification)3435Default: codify. Exception: justify not codifying.3637## Workflow: Calibrate3839When the agent makes a wrong decision mid-session:4041**The Norman Principle applies here.** The agent didn't fail — the harness did.42"I knew better" is not a valid analysis. If the system let the agent make the43error, the system is badly designed. If the system's own instructions induced44the error, it's really badly designed.45461. **What went wrong?** — Describe the incorrect decision472. **Why?** — Root cause in the harness (missing context, wrong instruction, stale rule)483. **Induction check** — Did the harness *cause* the error? Conflicting instructions,49 stale context, misleading skill descriptions, missing hooks that would have50 prevented it? Induction errors are the highest-priority fixes.515. **Fix the harness** — Update the source of the problem:52 - Wrong AGENTS.md instruction → fix AGENTS.md53 - Missing hook → add hook54 - Stale skill reference → update skill55 - Missing test → add test566. **Then fix the code** — The code fix should be trivial now5758The harness fix is the real deliverable, not the code fix.5960## Workflow: Tune-Repo6162Refresh context artifacts for a target repo. Run proactively or after63noticing drift between docs and code.64651. **Scan** — Read AGENTS.md, CLAUDE.md, and any skill references. Compare66 against actual codebase state (do referenced files/functions still exist?).672. **Flag drift** — List stale entries, broken references, missing sections.683. **Check essentials** — Does AGENTS.md include:69 - After Compaction recovery instruction? (If not, add one.)70 - "Plausible ≠ correct" red line? (If not, add one.)71 - Build/test/lint commands? (If not, add from package.json/Makefile.)724. **Fix** — Update stale content. Delete what's wrong. Add what's missing.735. **Report** — What was updated, what was deleted, what was added.7475## Codification Hierarchy7677When encoding knowledge, always target the highest-leverage mechanism:7879| Level | Mechanism | Reliability |80|-------|-----------|-------------|81| 1 | Type system | Compile-time guarantee |82| 2 | Lint rule | Blocks on violation |83| 3 | Hook | Runs on every tool use |84| 4 | Test | Catches regressions |85| 5 | CI gate | Blocks merges |86| 6 | Skill/reference | Agent reads on demand |87| 7 | AGENTS.md | Agent reads at session start |88| 8 | Memory | Last resort, least reliable |8990## Gap Types9192When a session reveals something MISSING:9394| Gap | Signal | Fix |95|-----|--------|-----|96| missing_skill | Had to improvise a reusable workflow | Create skill |97| missing_tool | No available tool provided capability | Hook or MCP |98| repeated_failure | Same error class across sessions | Lint rule or guardrail |99| wrong_info | Acted on stale AGENTS.md or reference | Update source doc |100| permission_friction | Correct action blocked | Hook or settings |101102## Retro Storage103104Issue-scoped feedback: `{repo}/.groom/retro/<issue>.md`105One file per issue. Feeds `/groom`'s planning loop.106107## Gotchas108109- **Reflecting without artifacts:** If reflect doesn't produce a commit (hook, rule, skill update, AGENTS.md edit), it was a waste.110- **Codifying at the wrong level:** Writing a CLAUDE.md line when a hook would be more reliable. Use the hierarchy — type system > lint > hook > test > ... > memory.111- **Fixing only the code:** When calibrate mode triggers, the harness fix IS the deliverable. The code fix should be trivial after.112- **Stale context is worse than no context:** A wrong instruction in AGENTS.md causes more harm than a gap. When in doubt, delete stale content.113- **Over-codifying obvious patterns:** If the model handles it natively, don't write a skill for it. Run `/harness eval` to check.
VRIL-LABS