# The cairn-method The cairn-method is a working discipline, not a feature. cairn gives an agent a durable place to keep work; the cairn-method is how an agent uses that place so a fresh session can pick the work back up. It is a loop with four phases: research, plan, implement, validate. Two heartbeat writes hold the phases together — `observe` and `handoff` — and one orienting read, `task_bootstrap`, re-enters the loop after a reset. The method ships as a skill (`cairn-method`) and six bundled prompts, so the agent reading this page can load the same discipline that authored it. ## Why a method and not just tools A model can call [the fourteen tools](/cairn/reference/tools) without any method and get nothing durable. The graph fills with tasks that have no observations, plans whose phases never settle, handoffs that summarize nothing a next session can act on. The tools are necessary but insufficient on their own. What makes the work resumable is the order the agent writes in — what it records, when, and against which task. The cairn-method names that order. It says: orient before writing, record findings as they surface, structure the plan as a graph the frontier can read, advance only on a real gate, and leave a summary the next session reads first. Each rule maps onto a tool or a query that already exists. The method is the contract between the agent and its future self. ## The loop The method runs as a loop across sessions, not a script inside one. A session enters by orienting, does one kind of work, and leaves a trail. The next session — the same agent after a context reset, or a different one — enters the same way and continues. This section is the cross-session heartbeat — orient, record, hand off; the four work phases (next section) run inside it. **Orient.** A session begins with [`task_bootstrap`](/cairn/reference/tools#task-bootstrap). One call returns the task's state, its neighbors, any open handoffs, and the recent observations. An explicit `task_id` switches the [current-task pointer](/cairn/concepts/the-current-task-pointer) to that task; with no `task_id`, it orients on the current task and adopts it only when one is not yet set. Called with neither a `task_id` nor a current task, it returns `No task to bootstrap; pass task_id or select a task first.` `task_bootstrap` records no event, so re-entering costs nothing — the call repeats freely whenever the thread is lost. **Record.** Throughout the work, [`observe`](/cairn/reference/tools#observe) is the heartbeat — the cheapest write cairn has. It appends one freeform observation to the current task and returns `Observed on .` It does not move the pointer and it does not need a status change to justify it. The cairn-method favors liberal observation over a mandated cadence: a research finding, a red-then-green test, a constraint hit, a decision made. These observations are what [`task_search`](/cairn/reference/tools#task-search) later retrieves, so a finding written once need never be re-derived. **Hand off.** When the work spans sessions, [`handoff`](/cairn/reference/tools#handoff) scaffolds a resumable note. The one-line summary comes first and is the load-bearing field a resuming session reads before anything else; the tool returns `Handoff scaffolded for at ` and writes a skeleton, which a rich body then overwrites. The summary is the contract; the file supplements the live timeline and observations, and never contradicts them. When the two disagree, the live stream wins. This loop is recursive: the page you are reading was produced by an agent running it — see [What cairn is](/cairn/concepts/what-cairn-is) for that story in full. ## The four phases Inside the loop, the work itself moves through four phases. Each ships as a prompt — `research`, `plan`, `implement`, `validate` — and each leans on the `cairn-method` skill for the discipline rather than restating it. Two more prompts, `handoff` and `resume`, wrap the loop's heartbeat and re-entry. Six prompts in total. **Research documents what is.** Before anything changes, research documents the codebase as it stands — findings, not prescriptions. Every claim carries a `file:line` or a source URL; hypotheses stay phrased as hypotheses until a root cause is reproduced. The method requires a current task before any current-scoped write, because `observe` and the `knowledge` query both resolve against it, and every finding then sinks through `observe`. It also expects a `task_search` before re-investigation, since the answer may already be in the graph. **Plan structures the work as a graph.** A plan in cairn is a task DAG, not a markdown file — [the graph is the source of truth](/cairn/concepts/plans-phases-and-the-frontier). Phases are child tasks created with [`task_fork`](/cairn/reference/tools#task-fork) (default edge `phase-of`); real prerequisite ordering is a `depends-on` edge added with [`task_link`](/cairn/reference/tools#task-link). Because `task_fork` makes the new child current unconditionally, the method always names the parent with `from=`. Each phase carries its own acceptance and is independently verifiable. There is no scaffold tool; the edges are built with the tools above. **Implement advances on real gates.** Work moves through the DAG one ready phase at a time, asking `(query "plan-frontier")` for the next phase whose every `depends-on` predecessor is settled. A phase can be advanced without moving the pointer: passing `task_id=` to `observe` and [`task_update_status`](/cairn/reference/tools#task-update-status) targets it while the plan stays current. The gate is irreducible — no phase reaches `completed` until its build, tests, and typecheck actually pass. The passing output advances the DAG, not vibes. **Validate is independent and skeptical.** A separate pass runs the gates itself rather than trusting a self-reported result, reviews the code against the DAG, and reports honestly. It reads `(query "plan")` for completion status, `(query "stale-phases")` for phases active under a finished parent, and `timeline` to reconstruct what was actually done. It classifies findings as matches, deviations, or potential issues, each with a `file:line`, and refuses to green-light advancement while build or test failures remain. These phases are documentarian and test-first by design. The method documents what is, not what should be; it writes the failing test first, for the right reason; it leaves zero `TODO`/`FIXME`/`HACK` in shipped code. It treats honest deviation as content — when reality differs from the plan, the agent pauses, surfaces the gap, gets a decision, and records it with `observe`. ## Where the method is overkill The cairn-method earns its weight when work outlives a single context window — multi-session efforts, plans with real phase ordering, or several agents touching the same tree. It is overkill for a one-off task finished in one sitting and never resumed. For a single quick change, a `task_create` and one `observe` is the whole method; forking phases and writing a handoff for work that ends in the same turn is ceremony, not continuity. The full loop is for the case where a reset would otherwise cost the context — that is what cairn exists for. When it would not, a plainer note wins. ## Related - [What cairn is](/cairn/concepts/what-cairn-is) — continuity for agents, and the recursive loop in depth - [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier) — why a plan is a DAG and how the frontier picks the ready work - [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs) — the three nouns the loop writes - [The current-task pointer](/cairn/concepts/the-current-task-pointer) — what `task_bootstrap` and `task_fork` move, and what `task_id` leaves alone - [Serve cairn over MCP](/cairn/cli/mcp-serve) — exposing the tools, the six prompts, and the cairn-method skill over MCP