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

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

Step 1 — Review session work

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:

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

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.

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:

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:

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

If primary is not on main, skip propagation — the next git pull will pick it up.

Step 4 — Write to Basic Memory vault

Use mcp__basic-memory__search_notes first to avoid duplicates, then mcp__basic-memory__write_note or mcp__basic-memory__edit_note. Use [[wiki-links]] for connections. Tag every note with the current project name.

If Basic Memory MCP is not connected, log the skip in the output summary and continue. Do not block.

Step 5 — ADR check

If a significant architectural decision, convention, or recurring pattern emerged, prompt:

Should this become an ADR? Candidate: "<pattern summary>". (y/n)

If yes: create ai-workspace/decisions/ADR-NNN-<slug>.md using the template at ai-workspace/decisions/TEMPLATE.md. Increment the highest existing ADR number.

Step 6 — Create issues from surfaced work

Check for duplicates first (open and recently closed):

gh issue list --state open --limit 100 --json number,title
gh issue list --state closed --limit 20 --json number,title

Source (a) — Reflect TODOs: gotchas, follow-ups, technical debt surfaced during Steps 1–5. Create a GitHub issue for each with no duplicate.

Source (b) — Scratchpad (ai-workspace/scratchpad.md): for each line matching - [ ] ... → create issue → rewrite as - [x] → #N. Leave plain bullets untouched — they are reference notes.

Step 7 — Finalize plan

Rename the active plan to .done.md. Verify Outcomes & Learnings is filled in first.

mv ai-workspace/plans/<name>.md ai-workspace/plans/<name>.done.md

This commit can go on the primary worktree — .done.md plan files are in the allowlist (see task-branches.md). Skip if no active plan.

Step 8 — Phase gate

Read .branch-context.md:

• MEMORY.md not updated + .branch-context.md had content → soft block: warn and do not declare task complete until resolved.
• .branch-context.md missing or empty → warn but do not block.

Output summary