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 -10Review 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
| 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.
REFLECT_DIR="$CLAUDE_SESSION_DIR/memory-reflect"
[ -d "$REFLECT_DIR" ] && rm -rf "$REFLECT_DIR"
git clone --depth 1 "$(git remote get-url origin)" "$REFLECT_DIR"Retry loop (max 3 attempts):
- Read
$REFLECT_DIR/ai-workspace/MEMORY.mdas it exists now. - Re-derive entries from the current file state — skip anything already present, avoid duplicates. Do not auto-merge. Do not replay old diffs.
- Add new entries. Prune entries older than 30 days. Keep under 200 lines — if over, summarize the oldest section (never silently delete).
- 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- On non-fast-forward rejection:
git -C "$REFLECT_DIR" pull --rebase, return to step 1. - 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.
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: "". (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,titleSource (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.mdThis 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
| Layer | Action |
|---|---|
| MEMORY.md | N entries added, N pruned (X lines total) |
| Basic Memory | N notes written/updated (or: skipped — MCP unavailable) |
| Issues closed | #N, #N (verified) / #N still open (warned) |
| Issues created | #N "", #N "" |
| Issues commented | #N |
| ADR | Created ADR-NNN / Skipped |
| Plan | Finalized.done.md / None |
| Phase gate | MEMORY.md updated: yes/no —.branch-context.md: found/missing |