cairn

name	cairn
description	Maintain a small repo-local recovery checkpoint in CAIRN.md. Use when a repository contains CAIRN.md, or when the user asks to use Cairn to set up, resume, park, hand off, or record work.

Cairn

A cairn marks where work stands so a fresh session can continue without conversation history. It is a checkpoint, not a diary or a second project tracker. It tracks one current work item; when work switches, retarget it rather than opening a second checkpoint.

Scope

When CAIRN.md exists at the repository root, follow the work loop below. A setup request against an existing checkpoint may correct or refresh it, but never replaces it.

When it does not exist:

• When the user asks to set up, park, hand off, or record work with Cairn, create it from assets/CAIRN.md and populate it from the current work, including the failed routes and consequential external actions of the session being recorded. Verify against current files and, when available, Git rather than trusting recall.
• When asked to resume with Cairn, report that no checkpoint exists; do not invent one.
• Otherwise take no Cairn-specific action and continue the task normally.

Whenever Cairn creates CAIRN.md, and on every setup request, install or refresh the assets/AGENTS.snippet.md block in the repository's AGENTS.md: replace one complete cairn:begin through cairn:end block, or append it if absent, preserving all other content and creating the file if needed. Report malformed or repeated markers instead of guessing.

Work loop

These steps assume the task permits repository edits. When it does not, report what the checkpoint gets wrong or lacks instead of writing to it.

1. Read CAIRN.md before task work and verify its claims against current reality. In a Git repository, always inspect git status --short. When HEAD exists, find the last committed checkpoint with git log -1 --format=%H -- CAIRN.md; when one exists, inspect later committed changes with git diff <checkpoint-commit>..HEAD --stat. If no checkpoint commit exists, or CAIRN.md is modified or untracked, verify its current contents directly against the working tree. Without Git, verify current files and observations directly; do not use a timestamp as evidence of freshness. Correct stale claims and confirm the checkpoint's Next action still holds before acting on it.
2. Record a failed approach, hard-to-reverse decision, or consequential external action when it occurs, rather than waiting until the end of the turn.
3. Update the checkpoint before ending a turn only if recovery-critical information changed.
4. Before retargeting or completing the checkpoint, preserve a completed, abandoned, or parked attempt when its evidence, conclusion, or resume point would otherwise be lost. Capture its premise, method, evidence, conclusion, and any resume point — enough that it need not be rerun or re-derived. Use an existing durable project record only when it is accessible and writing there is authorized; updating an external issue tracker requires separate authorization. Otherwise carry a compact parked-attempt record in Current state across the retarget. Use Ruled out for abandoned or failed routes and Decisions for actual decisions. Never put work history in AGENTS.md.

When an authorized update touches an older checkpoint, normalize misplaced content to these meanings without discarding it.

Checkpoint

Keep four sections current:

• Goal: the outcome and its observable done condition.
• Current state: what is true now. Name relevant files, symbols, commands, or output instead of abstract progress; include working or broken behavior and important uncommitted, untracked, no-VCS, or external state. Say when recovery depends on the current working tree.
• Next action: exactly one concrete action. If blocked, name the first action after the blocker clears using Blocked — <reason>; when <condition>, <first action>. Use None — complete only after Verification passes.
• Verification: the exact command or observation that proves success, then a Success: line naming the output or result that counts as passing.

Add Ruled out, Decisions, or Open questions only when a fresh session would need them.

Replace stale state instead of appending a history: keep the intent, evidence, failed routes, decisions, and precise resumption point, and nothing else. Where a durable record exists, link it from Current state or Ruled out and summarize it in one line instead of copying its history in; where none exists, write the recovery-critical substance in the appropriate Cairn section.

On completion, retain the four core sections and the final result and verification. Prune only stale process detail and optional content that no longer affects future work. Do not delete CAIRN.md during normal completion; an explicit user request may remove it.

Follow the user's instructions and the repository's normal workflow for commits. Never create a commit solely because Cairn exists or override rules that gate commits on passing tests. When a commit is authorized, include CAIRN.md with the related work. Otherwise record its exact modified or untracked state, and the state of the work it describes, in Current state.

An uncommitted checkpoint helps a fresh session resume in the same working tree; it does not make uncommitted code portable to a fresh clone. Portability requires the work itself to be persisted through the project's authorized workflow.