Curating Context

Curating Context

Announce at start: "I'm using the curating-context skill with the Context Curator persona to capture session context."

Overview

Capture session context into two outputs: a public handoff (committed to the repo, tone-firewalled, token-budgeted) and a private memory file (gitignored, unfiltered, full candor). The public handoff makes the next agent or human effective as fast as possible. The private memory preserves the full picture for future-you.

When to Use

• End of a work session (before closing the conversation)
• Switching focus to a different area of the codebase
• After a significant decision point that changes project direction
• When you realize accumulated context would be lost without capture
• Before handing off to another agent or team member

When NOT to Use

• For a single technical decision — use capturing-decisions instead
• For project documentation aimed at end users — use writing-end-user-docs
• For release notes or changelogs — use writing-changelogs
• For formalizing a design — use writing-design-docs

Quick Reference

Session Snapshot

The following is injected at skill load time — no tool calls needed.

Branch: !git branch --show-current 2>/dev/null || echo "(not a git repo)"

Recent commits: !git log --oneline -15 2>/dev/null || echo "(no git history)"

Working tree: !git status --short 2>/dev/null || echo "(clean)"

Staged/unstaged diff summary: !git diff --stat HEAD 2>/dev/null

Existing handoffs: !ls -t .handoffs/*.md 2>/dev/null | head -5 || echo "(none)"

Process

NOTE: Do not generate the filename date-time stamp until immediately prior to writing the file. Do not guess the date or time.

Step 1: Gather context

Use the session snapshot above as your starting point. Then review:

• What was accomplished this session?
• What decisions were made, and why?
• What's the current state of the codebase? (tests passing? broken? in-progress?)
• What should the next person do first?
• What will surprise or confuse someone who hasn't been staring at this code?

Step 2: Capture private context

Capture your unfiltered private context first — before writing the public handoff. Don't self-censor. This never reaches the repository.

Use whatever private capture mechanism is already configured in this session:

• If a private-journal MCP tool is available, use it (preferred — centralized, dated)
• If the user's global rules specify a journal location, use that
• If neither is available, write or append to PRIVATE_MEMORY.md in the project root (gitignored by convention — ensure .gitignore includes it)

The mechanism matters less than the content. Focus on what changes future behavior:

• User corrections and pushback — what was said, why, what to do differently
• Approaches that worked well — what clicked, what to repeat
• Platform/tooling gotchas that burned real time
• Design principles articulated that aren't obvious from code
• Motivations, frustrations, hunches about project direction

Step 3: Write the public handoff

Load the Context Curator persona from ${CLAUDE_PLUGIN_ROOT}/personas/context-curator.md (public mode).

Dialect: Check for BITO_DIALECT environment variable or the project's bito config for a dialect preference (en-us, en-gb, en-ca, en-au). If set, use that dialect's spelling conventions consistently throughout the draft. If not set, default to en-US.

Use the handoff template from ${CLAUDE_PLUGIN_ROOT}/templates/handoff.md. Fill every section:

1. Where things stand — Current state in 2-3 sentences. What works, what doesn't yet.
2. Decisions made — Bulleted, with brief rationale or link to ADR.
3. What's next — Prioritized, actionable, with file:line pointers where helpful.
4. Landmines — Specific things that will bite the next reader.

Step 4: Check quality

Before saving the public handoff, verify:

• Self-contained? Could a stranger with repo access start working from this document alone?
• Token budget? Target under 2,000 tokens. If tooling is available, run the token counter. If not, keep it to roughly one screen of text.
• No assumed context? No "as discussed" or "per our conversation" without a link to where it's captured.
• Landmines section populated? If empty, think harder. What will confuse someone who wasn't here?
• State color honest? Green/Yellow/Red reflects reality, not optimism.

Step 5: Tone firewall (public handoff only)

If the editorial-review skill or agent is available, run the public handoff through it. If not, self-check against the conference-talk test: would every sentence in this document be comfortable to say aloud at a technical deep-dive conference?

Specifically check for:

• Negative mentions of people, projects, or products
• Frustration or sarcasm that leaked from private thinking
• Implied criticism ("unlike the previous approach...")
• Jargon or inside references that assume context

Integration

• Replaces and enhances the standalone handoff skill
• Pairs with capturing-decisions — if decisions were made this session, capture them as ADRs and reference them from the handoff
• Feeds into the next session's onboarding — the handoff is the first thing the next agent reads
• Used by branch completion workflows as the final context capture before merge

Common Mistakes

Converted and distributed by TomeVault — claim your Tome and manage your conversions.