Wrap a Memex Milestone Slice
Close the loop on a finished slice. A slice ships code; the wrap ships the
trail that lets the next session resume without re-deriving where things
stand. Two docs carry that trail — docs/CONTINUE_HERE.md (where we are,
what's next) and docs/ROADMAP.md (the milestone scoreboard) — and the
wrap leaves both consistent with what actually landed. It does not log
observations or run the verification gates itself; it confirms the first was
done (deferring to memex-observe) and hands off to the second (memex-verify).
When to Use
- You just finished a milestone slice in the memex repo (a
- [x]-sized
unit of work) and are about to commit and tag it.
- You are handing the next slice to a fresh session and need
CONTINUE_HERE.md to point at the right starting line.
CONTINUE_HERE.md §1 or ROADMAP.md's scoreboard has drifted behind
what actually shipped, and you want to reconcile them before moving on.
<!-- These triggers also appear in the description so discovery sees them
before the body loads. -->
Inputs
- Required: The memex repo checked out, with
cwd = repo root (a
checkout of github.com/pjt222/memex). All paths below are repo-relative.
- Required: A finished slice — code committed or staged, slice known
by its milestone + slice letter/number (e.g. "M5 Slice A").
- Required:
docs/CONTINUE_HERE.md and docs/ROADMAP.md present and
writable.
- Optional:
$MEMEX_STORE_PATH / $MEMEX_PG_URL — only needed if Step 3
ends up logging a new observation, and even then the logging itself is
delegated to memex-observe, which owns those prerequisites.
This skill edits docs and proposes git commands. It does not push, tag, or
run the test gate — those belong to commit-changes and memex-verify.
Procedure
Step 1: Update docs/CONTINUE_HERE.md §1 (current state) and §3 (next slice)
Read the file first; both sections are prose with a specific shape you must
match, not free-form.
# Orient: the "Last updated" line, §1 Current state, §3 Next milestone
sed -n '1,40p' docs/CONTINUE_HERE.md
awk '/^## 1\./,/^## 2\./' docs/CONTINUE_HERE.md
awk '/^## 3\./,/^## 3a\./' docs/CONTINUE_HERE.md
Then edit (use the Edit tool — keep surrounding prose intact):
Last updated: line near the top — set today's date and a one-line
summary of the slice (mirror the existing format: date — what landed +
the commit short-SHAs + branch + state).- §1 Current state — move the finished slice from "in progress / next"
into Shipped, following the existing
M_ ... (shortsha, tag vX.Y.Z)
cadence. If the slice opened new tech-debt or deferrals, note them where
the section already tracks those.
- §3 Next milestone — if this slice completed a milestone, advance §3 to
the next milestone (copy the goal / required-pieces / tasks-in-order /
definition-of-done shape from
ROADMAP.md). If the milestone has more
slices left, narrow §3's "tasks in order" to the next slice so the
fresh session starts on the right line.
Expected: §1 names the just-shipped slice under Shipped with its SHA(s)
and (if a milestone closed) tag; §3 describes the next concrete slice. The
Last updated: line reflects today.
On failure: If the section headers don't match (## 1. / ## 3.), the
doc has been restructured — re-read it top-to-bottom and adapt to its current
headings rather than forcing the old shape. Never fabricate a SHA; if the
commit doesn't exist yet, write (<commit pending>) and fill it after Step 4.
Step 2: Tick the docs/ROADMAP.md scoreboard
The scoreboard encodes completion two ways: a milestone header gains a
✅ (vX.Y.Z) suffix when the milestone is done, and each finished line item
flips - [ ] to - [x]. Read the relevant block first.
# Find the milestone block you're closing items in
awk '/^## M5/,/^## M6/' docs/ROADMAP.md
Then, with the Edit tool:
- Check the items you shipped: turn each finished
- [ ] into - [x].
Leave genuinely-incomplete or deferred items as - [ ] (a deferred item
often carries a — deferred to MX.Y note; preserve it).
- Mark the header only when the whole milestone is done — append
✅ (vX.Y.Z) to the ## MN — ... header, matching shipped milestones
above it (e.g. ## M4 — MCP ✅ (v0.4.0)). A milestone with any unchecked,
non-deferred item is not done — do not flag its header.
Expected: Every item the slice completed reads - [x]; the header shows
✅ (vX.Y.Z) if and only if all of its non-deferred items are checked. The
new version matches the tag you propose in Step 4.
On failure: If you're unsure whether an item is truly done versus
partially done, leave it - [ ] and note the partial state in
CONTINUE_HERE.md §1 instead — an over-optimistic scoreboard is the exact
drift this skill exists to prevent. Match the existing checkbox/version
formatting; don't invent a new style.
Step 3: Confirm any new observation is logged (defer to memex-observe)
A slice that surfaced a bias, a near-miss, or a reusable lesson should have a
matching observation in the bias-log. The wrap's job is to confirm that —
not to author the entry or restate the logging CLI.
# Quick existence check: does the bias-log already hold this slice's lesson?
sed -n '1,40p' docs/OBSERVATIONS.md
Decide:
- Nothing worth logging? Note that explicitly in
CONTINUE_HERE.md §1
("no new observations this slice") so the next session knows it was
considered, not skipped, and move on.
- A lesson is worth logging? Stop and run the
memex-observe skill to
add it. That skill owns the memex add --type observation ... command shape
(body piped via stdin, --title required) and the prerequisites. Do not
restate or inline that command here — invoke the skill.
The observation body shape lives in docs/OBSERVATIONS.md (the
authoritative "Two paths to add an observation" block is lines 10–21). The
current form (example, current as of v0.4.0; parsed by
crates/memex-extract/src/meditate_vipassana.rs) is:
N. **Title.** Body sentence(s). Mitigation: <what to do next time>. Origin: <date> + <context>.
Treat docs/OBSERVATIONS.md lines 10–21 as the source of truth for this
shape — if it has moved on from the v0.4.0 form, follow the file, not this
example.
Expected: Either a recorded decision that there's nothing to log (noted
in §1), or a new observation added via memex-observe with the next entry
number.
On failure: If you can't tell whether a lesson is observation-worthy,
err toward logging it — a redundant observation costs little; a lost one
costs a re-derivation next session.
Step 4: Propose the git tag and the commit subject
Don't commit or tag here — propose both so the operator (or the
commit-changes skill) can execute them. Use the memex commit convention:
subject = MN Slice X: <summary>.
# Surface what's staged/unstaged so the proposed subject matches reality
git -C . status --short
git -C . diff --stat
Propose:
- Commit subject —
MN Slice X: <imperative summary> (e.g.
M5 Slice A: per-file project helper + watcher skeleton). Keep the
subject tight; put the why and the doc-trail updates in the body.
- Tag — only when this slice closes a milestone. Propose the next
semver tag matching the
✅ (vX.Y.Z) you set in Step 2 (e.g. v0.5.0
for M5). A mid-milestone slice gets a commit but no tag — say so
explicitly rather than proposing a tag.
Present both as a ready-to-run block for the operator to confirm:
Proposed commit subject: M5 Slice A: per-file project helper + watcher skeleton
Proposed tag: (none — mid-milestone slice; tag at M5 close as v0.5.0)
Expected: A clearly-labeled proposal: one commit subject in
MN Slice X: form, and either a concrete vX.Y.Z tag (milestone close) or
an explicit "no tag this slice" note. Nothing is committed or tagged by this
skill.
On failure: If the milestone number / slice letter is ambiguous, read
ROADMAP.md and CONTINUE_HERE.md §3 to fix the MN and X; never guess
a version — derive it from the scoreboard you just ticked in Step 2.
Validation
Common Pitfalls
- Flagging a milestone header done while an item is still open. The
✅
on the header is an all-items claim. Tick items in Step 2 first, then check
the header only if nothing non-deferred remains.
- Restating the observation CLI here. Step 3 confirms logging happened;
it delegates the actual
memex add to memex-observe. Inlining the command
duplicates a surface that drifts — reference the skill instead.
- Running
memex init. That is the CLI store/db setup command, not part
of any wrap or session ritual. Wrapping a slice never calls memex init.
- Inventing a SHA or version. Derive the tag from the scoreboard you just
ticked; derive the SHA from
git log after the commit exists. Use a
(pending) placeholder rather than a fabricated value.
- Committing or tagging from this skill. The wrap proposes; execution is
commit-changes' job, and the test/format gate is memex-verify's. Keep
the boundary — don't let the heaviest skill absorb its neighbors.
- Hard-asserting a test count as a pass gate. That belongs to
memex-verify, and even there the gate is exit 0 / "test result: ok" —
counts (e.g. "~60 at v0.4.0") are informational and grow per milestone.
- Forcing the old doc shape after a restructure. If
## 1. / ## 3. or
the scoreboard headings have changed, adapt to the file as it is now; the
doc-reading order itself is owned by adapters/session-init.txt.
Related Skills
memex-init — the session-start counterpart: loads the trail this skill
writes. Wrap closes the loop that init opens.memex-observe — owns logging a bias-log observation; Step 3 defers to it
rather than restating its CLI.memex-verify — runs the test/format/build gate; the wrap proposes the
commit, verify confirms the slice is green before it lands.write-continue-here — the general-purpose continuation-file skill; this
skill is its memex-specific specialization for §1/§3 and the scoreboard.commit-changes — executes the commit subject and tag that Step 4 proposes.