Reflect

Phase gate: COMMIT checkpoint. Do not declare task complete until Step 8 passes.

Execute all steps in order. Escalate to the user only at explicit escalation points.

## Step 0 — Mark reflect timestamp

```bash
date +%s > "${CLAUDE_PROJECT_DIR}/ai-workspace/.last-reflect-ts"
```

## Step 1 — Review session work

```bash
git log --oneline -10
```

Review recent edits and corrections made during this session. If a completed plan exists in `ai-workspace/plans/` (Outcomes & Learnings filled in), use it as the primary source. Otherwise derive learnings directly from git history and session events. Build an explicit inventory of candidate learnings before moving on.

## Step 1b — Verify issue closure

Scan commit messages for closing keywords (case-insensitive): `closes`, `close`, `closed`, `fixes`, `fix`, `fixed`, `resolves`, `resolve`, `resolved` followed by `#N`.

For each issue number found:

```bash
gh issue view N --json state --jq '.state'
```

Warn if any referenced issue is still open. Do not block — warn and continue.

## Step 2 — Classify learnings

| Signal | Destination |
|---|---|
| References this repo's files, paths, configs, or project conventions | MEMORY.md only |
| General pattern, tool behavior, or preference applicable across projects | Basic Memory vault only |
| Both (project-specific instance of a cross-project pattern) | Both — cross-reference each entry to the other |

## Step 2b — Comment learnings on related issues

**Plan has `Issue: #N` in frontmatter**: post learnings directly as a comment on that issue. No confirmation needed — the link is explicit.

**No plan or no Issue field**: run `gh issue list --state open --json number,title,labels --limit 50`, fuzzy-match keywords against open issue titles. Confirm with user before posting to any fuzzy match. A bad auto-comment is worse than a missed one.

## Step 3 — Write to MEMORY.md (concurrent write protocol)

MEMORY.md lives on main and may receive concurrent writes. Never write from the current worktree.

```bash
REFLECT_DIR="${CLAUDE_SESSION_DIR:-$TMPDIR}/memory-reflect"
[ -d "$REFLECT_DIR" ] && rm -rf "$REFLECT_DIR"
git clone --depth 50 "$(git remote get-url origin)" "$REFLECT_DIR"
```

Retry loop (max 3 attempts):

1. Read `$REFLECT_DIR/ai-workspace/MEMORY.md` as it exists now.
2. Re-derive entries from the current file state — skip anything already present, avoid duplicates. Do not auto-merge. Do not replay old diffs.
3. Add new entries. Prune entries older than 30 days. Keep under 200 lines — if over, summarize the oldest section (never silently delete).
4. Commit and push:

```bash
git -C "$REFLECT_DIR" add ai-workspace/MEMORY.md
git -C "$REFLECT_DIR" commit -m "reflect: update MEMORY.md [$(date +%Y-%m-%d)]

Co-Authored-By: Claude <model>"
git -C "$REFLECT_DIR" push
```

5. On non-fast-forward rejection: `git -C "$REFLECT_DIR" pull --rebase`, return to step 1.
6. After 3 failures, stop and escalate — do not proceed:
   > MEMORY.md write failed after 3 retries. Manual merge required at `$REFLECT_DIR/ai-workspace/MEMORY.md`.

### Propagate to primary worktree

After successful push, bring the primary worktree's main up to date so other agents see the new MEMORY.md immediately:

```bash
PRIMARY="$(git worktree list --porcelain | grep -m1 '^worktree ' | sed 's/^worktree //')"
CURRENT=$(git -C "$PRIMARY" branch --show-current)
if [ "$CURRENT" = "main" ]; then
  # WIP commit if dirty
  if [ -n "$(git -C "$PRIMARY" status --porcelain)" ]; then
    git -C "$PRIMARY" add -u
    git -C "$PRIMARY" commit -m "wip: preserve local state before reflect sync"
    WIP=1
  fi
  git -C "$PRIMARY" fetch origin main
  git -C "$PRIMARY" merge --ff-only origin/main || echo "Primary diverged — manual pull needed"
  # Restore WIP
  [ "${WIP:-}" = "1" ] && git -C "$PRIMARY" reset --soft HEAD~1
fi
```