ballast

Scaffold a file-based memory system (index, decision ledger, open questions, session log, optional product truth file) so a project can serve as a durable second brain. Use when the user wants to set up memory, an external brain, or the ballast structure in a project.

Maintain a thirty-second return point (CHECKPOINT.md) and a single-use handoff (HANDOFF.md) so any session can resume mid-goal without archaeology. Use when a large unit of work finishes, a session enters its closing stretch, when leaving instructions for the next session, or when resuming and the user asks where things stand.

Maintain an append-only decision ledger (DECISIONS.md). Use when the user confirms a decision, reverses or changes a past decision, asks what was decided and why, or at session start to load standing decisions.

Health check for the ballast installation — is the hook alive, are the catalogs sane, is anything silently dead. Use when rules stop arriving, the session-start line is missing, the user asks "is ballast working", or after an update or reinstall.

Run a large or unfamiliar goal through the full ballast pipeline — mobilize what you already hold, terrain scan, full skeleton, atomic foundation learning with verification, then build from bedrock to a verified done. Use when the user hands over a big goal, enters a new field, or asks to learn X in order to achieve Y.

Keep verified findings in memory/knowledge/ so the same research is never done twice. Use before researching any topic, when a finding passes the verify gate, or when about to answer from something learned in an earlier session.

Turn a correction or working preference the user just expressed into a permanent ballast rule. Use when the user corrects your behavior, says "don't do X" / "always do Y" / "I told you before", or asks you to remember how they want things done.

Never make an external-facing claim about a product without evidence from a truth file. Use when writing marketing copy, announcements, docs, landing pages, investor material, or answering "can our product do X".

Sweep everything the project already holds before answering — at the first message of a session, and again whenever the subject shifts to something the current thread was not about. Use before replying, not only before researching.

Test a deliverable on a zero-context reader before it ships. Use before shipping any document, guide, kit, or handoff meant to work without you, and before calling a deliverable done in goal Phase 5.

Read the delivery log and say which rules actually fire, which never have, and what to prune or fix. Use when the user asks whether ballast is doing anything, wants to clean up their rule catalog, or on a periodic review.

Delegate research collection to a configured second model — never the judgment. Use when .claude/ballast.researcher.json exists and facts must be gathered from outside the session, when a terrain scan is large, or before building something a standard method may already solve.

Own the calendar as a ledger - fixed dates, event-triggered entries, and launch bundles that fire together or not at all. Use when work has deadlines or submission windows, reacts to outside events (an outage, a deprecation, a competitor incident), or needs several deliverables published near-simultaneously.

Conversational first-time setup — prove the hook is alive, then build the user's first rule catalog without showing them JSON or regex. Use when the user just installed ballast, asks how to set it up or "where do rules go", or the session-start line says "no rule catalog yet".

Promote a procedure that was worked out end-to-end and verified into a reusable skill file, so the next similar task starts from the solved path. Use when a hard-won procedure succeeds with evidence, when the same multi-step task appears a second time, or when the user says "make this repeatable".

Treat research results and model knowledge as drafts until verified. Use when researching, quoting numbers or sources, recording knowledge as fact, or before declaring a task successful.