Methods and the mode
Table of Contents
Status: target state. This page describes the framework we are building, not the catalogue as it stands today. Where this page and the current catalogue disagree, the catalogue is what runs.
1. Summary
A method is this framework's instrument of sequencing: it constrains the order in which action is taken, which is one of the functions a regulator must discharge. It carries a piece of work from an unverified beginning to a verified end, and its phases are what make that progression checkable rather than asserted.
This document holds the catalogue of methods, the discipline their phases share, the mode that routes work to them, and the course a session takes through the framework as a whole.
The mode is a convenience over methods rather than a precondition for them. A method is invocable directly, and so is an action; the entry points are set out in Skill architecture.
2. Detail
Figure 1: compass-helm from a request to verified work.
compass-helm is the sticky entry point. Entered once, it stays on
across turns, applying itself when a method matches and staying out of
the way otherwise.
- Declares the System the session acts as, which attenuates the catalogue.
- Matches the request to a method and copies that method's phases into the todo list verbatim, before any task-specific reasoning. A phase deliberately skipped stays in the list with a stated reason.
- Reads the principles index at task start.
- Routes to actions and recipes as the phases fire, and to deliberation at a fork the evidence cannot settle.
- Spawns delegates as named Systems, never as generic agents, so the discipline survives the delegation boundary. The mode and its delegate System share one definition; there is no second place for the rules to drift.
Step 2 carries the value. The failure it guards against is an agent reading a method and then writing a bespoke plan that quietly drops the method's named phases.
2.1. The Request Shape
compass-helm <what you observed, or what you want> Done means <something the agent can run or inspect>. Keep <the behaviour that must not change>.
The finish condition names a result, not an amount of effort: "zero old callers and every parser fixture passes", never "work on this for a while".
Do not list the skills you want run. State the goal and the constraints; the method owns the sequence. An agent handed both a goal and a step-list follows the step-list and drops the method's gates.
2.2. Matching a Request to a Method
Matching is the first decision and the one no later phase recovers from, so it is a stated rule rather than a judgement made fresh each time.
2.2.1. The rule
Ask these in order and take the first that answers yes. They are ordered by how sharply they discriminate, not by how common they are.
- Does the work change nothing? The deliverable is an answer, a
diagnosis, a recommendation. →
compass-method-investigation. - Is something already behaving wrongly, observably, against a
contract already in force? There is a symptom someone could be
shown, and the behaviour was wrong when it happened rather than made
wrong afterwards. →
compass-method-bug-fix. - Does behaviour stay the same while structure changes? A rename, an
extraction, a collapse, a move. →
compass-method-refactoring. - Does the next decision hinge on something observable that nobody has
observed? →
compass-method-prototype, then match again once the fork is settled. - Otherwise, behaviour is new or changed. →
compass-method-feature.
Question 2 outranks question 5 deliberately. Work that adds a capability because the current one misbehaves is a defect first: fixing it without reproducing it is how a symptom gets papered over with a feature. A crash under load and an unhandled input both reproduce, root-cause and get fixed by adding what was missing, so bug fix is right even though the fix adds something.
The clause about a contract already in force is what stops question 2 swallowing everything. A requirement can change and recast behaviour nobody complained about as wrong: an endpoint that has returned 200 for a partial success since it shipped, and a new client that needs 207. That reads as observably wrong and is not a defect — nothing misbehaved, the requirement is what is new, and there is nothing to root-cause. It is question 5. Without the clause, any change of mind about what is correct could be phrased as a symptom and borrow the bug-fix machinery.
2.2.2. When two match
Two methods matching is nearly always one of two shapes, and they are handled differently.
- Two match the same work. The earlier question wins, because the ordering is by discrimination: a refactor that also fixes a defect is a defect, and the refactor follows separately once the fix has landed with its reproduction.
- Two match different parts of the work. Neither wins.
compass-method-figure-it-outsequences them, and each part runs under its own method inside that sequence. A migration across many call sites is this shape: a series of refactors that needs a plan of its own.
The test that separates them is whether one predicate can describe the finished state. If it can, it is one piece of work with two candidate methods; if it takes two, it is two pieces of work.
2.2.3. When none matches
First check the limits below. Most unmatched requests are unmatched because they are too small for a method at all, and the answer is a plain action skill rather than a bespoke sequence.
Where the work is substantial and genuinely fits no method, that is
compass-method-figure-it-out, whose first phase is to say which
methods were rejected and why. An unmatched request is a finding: if the
same shape arrives twice, the second time it should be matching
something.
2.3. Limits of the Mode
The machinery has a cost, and a mode that fires on everything trains people to route around it. Moving a date, fixing a sentence, changing one configuration value, answering a question — none of these need a declared System, a matched method, a grounding phase and a decision trail. Reach for the plain action skills.
The mode earns its cost when a plausible diff is not enough: work that must be reproduced before it is fixed, a design decision expensive to reverse, a run long enough that a human reviews it after the fact, or a domain the agent has not grounded itself in.
2.4. The Course of a Session
The sections above state what a method is. This states the order in which the framework's parts are reached during a piece of work, and it doubles as a reading order for someone meeting the cluster for the first time.
A session opens with compass-agile-find-bearings and declares its System,
which fixes the level and attenuates the catalogue
(Systems and levels). It picks up
work with compass-agile-find-heading and compass-agile-start-task, inheriting the sprint
mission and story goal as constraints from above.
It then enters compass-helm, which matches the work to a method and
copies that method's phases in. The method opens by
grounding itself in the domain, resolving each concept it touches to a
knowledge document and treating an unresolved one as the first task
(Regulatory Functions). Where
the concept belongs to a cluster with a
structure note, grounding reads
that note first and follows its order: it names which pages are
load-bearing and which can wait, which a search ranking cannot. Listing the
structure_note tag returns the clusters that have one. It states
a finish condition, backed by a specification where behaviour is involved.
The method's phases cite principles for judgement calls and call actions for anything touching an artefact, reaching for a recipe whenever a command is needed (Regulatory Functions). Where an artefact turns out to be generated, the edit goes to its model or template rather than its output (Generated artefacts). At a fork the evidence cannot settle, the method convenes deliberation and records the verdict on the task.
A missing effector becomes a recipe, never an inline command. When a phase needs a command no recipe carries, the command is written as a recipe and the phase reaches for it. Improvising it inline buys one session and costs every later one: the command is untested, it is invisible to compass-doc-sync-recipes, and the next method that needs the same effector improvises its own. The recipe holds the command and the skill holds the judgement, so drift has exactly one place to be detected.
Verification climbs the ladder as far as the work requires, routing
first to the checkers that do not share the session model's priors
(Verification). The session closes
with compass-agile-close-task and compass-pr-raise, and what generalises is routed into a
memory, a principle or a skill edit, with approval rather than automatically.
2.5. The methods
Six exist. Each opens by grounding the work and stating what would make it finished, and each names the actions and recipes its phases call rather than improvising a command.
| Method | The work it sequences |
|---|---|
| compass-method-bug-fix | A reported defect: reproduce, root-cause, fix, prove |
| compass-method-feature | New or changed behaviour, built from a named data shape |
| compass-method-refactoring | Structure changes, behaviour does not, and the proof is the deliverable |
| compass-method-investigation | A read-only question, answered with citations and its gaps named |
| compass-method-prototype | An empirical fork, settled by observing it and then deleted |
| compass-method-figure-it-out | Work no method fits: design the phases, then run them |
Matching is the first decision a session makes and the one most worth
getting right: a misjudged shape is the failure a method exists to
prevent, and no phase recovers from it. Where two match different parts,
compass-method-figure-it-out sequences them rather than replacing them.
3. See also
- The Cybernetic Skills Framework — sequencing among the regulatory functions.
- Skill architecture — the index into the cluster this page belongs to.
- Grounding — the obligation a method's opening phase discharges.
- Verification — the ladder a method's closing phases climb.
- Systems and levels — what the mode declares, and what it attenuates.
- Skills — the inventory the methods draw on.