reflect · diff
git:20260609.8401a9d to git:20260615.d335473
11 added, 11 removed. Audit A to A.
---
name: reflect
- description: Per-project self-improvement — reads the .harness ledger and feedback memories, then proposes gated rule/threshold/ADR changes so the project stops repeating mistakes. Run periodically.
+ description: Per-project self-improvement - reads the .harness ledger and feedback memories, then proposes gated rule/threshold/ADR changes so the project stops repeating mistakes. Run periodically.
user_invocable: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
---
# Reflect: Per-Project Self-Improvement
- You are performing a reflection — turning the signal this project has captured
+ You are performing a reflection - turning the signal this project has captured
into durable improvements. Nothing is applied without the developer's approval.
- ## Phase 1 — Orient (gather signal)
+ ## Phase 1 - Orient (gather signal)
- Run the stats script over the ledger:
`~/.claude/hooks/harness-ledger-stats.sh --ledger .harness/ledger.jsonl --min-recurr 3`
- If that path doesn't exist, the hooks aren't installed at `~/.claude/hooks/` — run the
+ If that path doesn't exist, the hooks aren't installed at `~/.claude/hooks/` - run the
copy from wherever this project keeps them. If the script prints all zeros there is no
- ledger yet (no signal captured) — stop; there is nothing to reflect on.
+ ledger yet (no signal captured) - stop; there is nothing to reflect on.
- Read the current project rules in `CLAUDE.md` so you improve them rather than duplicate.
- - Read recent `feedback`-type memory files — these are the developer's explicit
+ - Read recent `feedback`-type memory files - these are the developer's explicit
corrections and are the highest-value signal. Locate the memory directory first
(it sits next to `MEMORY.md`; `find . -name MEMORY.md` if unsure), then
`grep -l 'type: feedback' <memory-dir>/*.md`.
- Read the most recent `.harness/reflections/*.md` report (if any) to recall the last
metric snapshot and what was already changed.
- ## Phase 2 — Cluster
+ ## Phase 2 - Cluster
From the stats output and feedback memories, identify recurring problems:
- - Each `recurring <rule> <prefix> <count>` line is a friction cluster — the same check
+ - Each `recurring <rule> <prefix> <count>` line is a friction cluster - the same check
keeps firing in the same area.
- Group related feedback corrections by theme.
- Ignore one-off events; focus on what repeats.
- ## Phase 3 — Propose (one candidate per cluster)
+ ## Phase 3 - Propose (one candidate per cluster)
For each cluster, draft exactly one proposed change, choosing the fitting type:
| Type | When | Where it lands |
|------|------|----------------|
| **Project rule** | a convention would stop the repeat | append to `CLAUDE.md` project-specific section |
- | **Threshold change** | a guardrail is too strict/loose | a diff to `.claude/settings.json` or the hook — **shown, never auto-applied** |
+ | **Threshold change** | a guardrail is too strict/loose | a diff to `.claude/settings.json` or the hook - **shown, never auto-applied** |
| **Lint rule** | the mistake is mechanically catchable | a diff to `eslint.config.mjs` / `biome.json` |
| **ADR / knowledge** | durable "why" worth keeping | a new memory file or `docs/adr/` note |
Present all proposals together as a numbered list with the concrete change for each.
- ## Phase 4 — Gate & Record
+ ## Phase 4 - Gate & Record
- Ask the developer to approve, edit, or reject each proposal (like `/remember`).
- Apply only the approved ones, then commit them (use `/commit`).
- Create `.harness/reflections/` if needed (`mkdir -p .harness/reflections`), then write a
reflection report to `.harness/reflections/YYYY-MM-DD.md` containing:
- the full stats output (the **metric snapshot**, so the next reflection can compare),
- the clusters you found,
- which proposals were approved / rejected and why.
The report is committed; the raw `.harness/ledger.jsonl` stays gitignored. Signal is
private; wisdom is shared.
## Measuring success
The headline metric is `recurring_events` from the stats output. Compare it to the value
in the previous reflection report. If a rule you promoted last time worked, the cluster it
targeted should have shrunk. Note the trend explicitly in the new report.