SKILL.md

$27

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:-$TMPDIR}/memory-reflect"

[ -d "$REFLECT_DIR" ] &#x26;&#x26; rm -rf "$REFLECT_DIR"

git clone --depth 50 "$(git remote get-url origin)" "$REFLECT_DIR"

Retry loop (max 3 attempts):

Read $REFLECT_DIR/ai-workspace/MEMORY.md as 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.

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" ] &#x26;&#x26; 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: "". (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

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

ADR

Created ADR-NNN / Skipped

Plan

Finalized .done.md / None

Phase gate

MEMORY.md updated: yes/no — .branch-context.md: found/missing

reflect