@assuredloop/orca-bot-kit 0.2.0 → 0.4.0

package/README.md

@@ -71,8 +71,10 @@ obk --version
 The command is `obk`. If `obk --version` does not answer after that, npm has no
 working release yet (an early placeholder has no `obk` in it): run
 `npm uninstall -g @assuredloop/orca-bot-kit`, then install from a clone of this
-repository with `npm install` and `npm link`. The same clone route is how you
-work on the kit itself: `obk` then runs your checkout.
+repository with `npm install` and `npm link`. To work on the kit itself, run
+your clone's `src/cli.js` by its full path instead of linking it: the `obk` on
+PATH stays the published one, and the kit calls itself back by the path of the
+CLI that started it, so what your clone brings up calls back into your clone.
 
 Releases go out from CI: publishing a GitHub Release tagged `v<version>` runs
 `.github/workflows/publish.yml`, which runs the suite and publishes that version
@@ -99,7 +101,7 @@ my-bots/
 
 The folder is yours. It holds your configuration and none of the kit's code —
 kit skills are linked from the installed package, never copied
-([ADR 0004](docs/adr/0004-skills-are-linked-never-copied.md)). Run `init` again
+([ADR 0014](docs/adr/0014-skills-are-linked-never-copied.md)). Run `init` again
 whenever you like: it adds what is missing and leaves everything else, including
 your edits, exactly as it is. It does not commit for you.
 
@@ -136,7 +138,7 @@ note about it. Anything you leave out is the
 harness's own default; the kit names no model of its own. The approval level is
 `auto` — the harness's real auto mode — unless you ask for `ask` or, in those
 words, `dangerously-skip`
-([ADR 0005](docs/adr/0005-three-approval-levels-auto-by-default.md)).
+([ADR 0015](docs/adr/0015-three-approval-levels-auto-by-default.md)).
 
 Neither command touches Orca. `obk up` is what makes it all real there: an Orca
 project per bot, a tab per session, each started at the bot home with its own
@@ -148,7 +150,7 @@ so run it after a restart, or whenever something is missing. `--bot` and
 
 Each bot has one `AGENTS.md`, shared by all its sessions: its charter, then the
 rule units it uses
-([ADR 0003](docs/adr/0003-agents-md-is-compiled-from-rule-units.md)). A rule
+([ADR 0013](docs/adr/0013-agents-md-is-compiled-from-rule-units.md)). A rule
 unit is one short block of always-on working rules. The kit's own units live in
 [`rules/`](rules/) in this package; yours go in `rules/` inside your bots
 folder. What is always on stays short, because every session reads it on every
@@ -216,7 +218,7 @@ size the always-on set may reach.
 
 The kit ships its own skills in [`skills/`](skills/), one directory per skill,
 named `obk-<technique>`
-([ADR 0009](docs/adr/0009-skills-by-technique-with-a-prefix.md)). They are
+([ADR 0019](docs/adr/0019-skills-by-technique-with-a-prefix.md)). They are
 organised by technique rather than by role: a role is a charter plus a choice
 of skills. Each one gives techniques and defaults, never a process or
 a way of working you have to adopt, and carries what it needs itself rather
@@ -261,12 +263,22 @@ name for a directory in `skills/` inside your bots folder, or anything with a
 `/` in it for a skill directory anywhere on disk. `obk up` links them before it
 opens a tab, and `bot create` gives a new bot what the lists already name.
 
+A bot whose sessions are running gets a changed list without a restart.
+When `skills build` links or takes away a skill, it tells each running
+session of that bot. A Claude Code session gets `/reload-skills` typed into
+its tab: Claude Code's own reload, which a busy session runs when its turn
+ends. Codex has no reload command and takes the change at the start of its
+next turn, so nothing is typed there. The kit prints the new skills'
+`SKILL.md` paths, and says that a restart would make a skill appear if it is
+still missing after that turn. A session the kit could not tell is named,
+with the reason.
+
 What lands in the bot is a symlink, never a copy
-([ADR 0004](docs/adr/0004-skills-are-linked-never-copied.md)) — into
+([ADR 0014](docs/adr/0014-skills-are-linked-never-copied.md)) — into
 `.claude/skills` and `.agents/skills` in the bot home, which is where each
 harness reads a project's skills from. So a kit skill is read where npm
-installed it, editing a skill is what a running session reads without a
-restart, and updating the kit updates every bot at once.
+installed it, a running session reads an edited skill the next time it loads
+it, and updating the kit updates every bot at once.
 
 The kit takes away only what it can prove it put there. It writes down every
 link it makes, in `.obk-skills.yaml` in the bot folder, and when no list names
@@ -307,7 +319,7 @@ with no rebuild, because the link points at the clone.
 
 The kit says one line when a source carries scripts or hooks. It does not read
 them and does not stand in your way — a third-party skill is your risk to take
-([ADR 0004](docs/adr/0004-skills-are-linked-never-copied.md)).
+([ADR 0014](docs/adr/0014-skills-are-linked-never-copied.md)).
 
 A skill is a directory holding `SKILL.md` — frontmatter carrying `name` (the
 directory's own name) and `description`, then the body — plus any reference
@@ -324,11 +336,11 @@ own directory, because a bot gets the directory alone.
 Each bot keeps a book, `sessions.yaml` in its folder: which Orca tab each session
 lives in, which harness session it is running as, and every id it ran as before,
 with why that one ended and when
-([ADR 0002](docs/adr/0002-the-book-is-the-authority-for-session-ids.md)).
+([ADR 0012](docs/adr/0012-the-book-is-the-authority-for-session-ids.md)).
 
 The book stays true to the harness through a hook `obk up` puts in the bot's own
 folder — `.claude/settings.json` or `.codex/hooks.json`, never your user-level
-settings ([ADR 0010](docs/adr/0010-kit-hooks-live-in-the-bot-folder.md)). Your own
+settings ([ADR 0020](docs/adr/0020-kit-hooks-live-in-the-bot-folder.md)). Your own
 settings in those files are kept. Codex asks you to trust a hooks file the first
 time it sees one; answer its question in the tab.
 
@@ -402,8 +414,12 @@ same refusals, and `obk up` leaves what is paused closed until `obk unpause`
 brings it back with its conversations. Retiring a session takes it off the bot
 and keeps its conversations in the book under `retired`. Retiring a bot closes
 its tabs, removes its Orca project and moves its folder to `retired/`; it will
-not touch a bot whose Orca project holds a tab your book does not name. Bot
-Father itself is never paused or retired.
+not touch a bot whose Orca project holds a tab your book does not name. The
+folder moves only once Orca no longer lists the project; if Orca still lists it,
+or its list cannot be read, retire says so and leaves the bot where it is, and
+retiring it again finishes the job. Bot
+Father itself, and its management session `daily`, are never paused or
+retired; its other sessions are like any bot's.
 
 ## When something is wrong
 
@@ -443,7 +459,7 @@ verdict: which of these matter, and in what order, is for you or for Bot Father.
 ## Sessions and bots that talk
 
 Ask the kit how to reach a session, and it answers with the road and the
-address ([ADR 0008](docs/adr/0008-messaging-transport.md)):
+address ([ADR 0018](docs/adr/0018-messaging-transport.md)):
 
 ```sh
 obk message to    --bots /path/to/my-bots --to api-bot/daily

package/SETUP.md

@@ -145,8 +145,9 @@ different answers.
 
 `obk init` tells you which, for every tab it opened:
 
-- *the harness was typed in and came up* — it is running. It may still be asking
-  something of its own; that is the table below.
+- *the harness was typed in and is running. The kit cannot see whether a screen
+  in it is waiting for an answer* — look at it: Orca does not flag every first-run
+  screen, so it may still be asking something of its own. That is the table below.
 - *the harness was typed in and came up, waiting on: …* — running and blocked on
   a question. The table below.
 - *the harness was typed in, and no session came up in the tab* — **the line did
@@ -183,8 +184,9 @@ waiting for:
 | On screen | Send | Which is |
 |---|---|---|
 | Claude Code's folder trust list | `\x1b[B\r` | down, then return: its selection starts on **No, exit** |
-| Codex's directory trust, `1. Yes, continue` | `1\r` | yes |
+| Codex's directory trust, `1. Trust and continue` (older: `1. Yes, continue`) | `1\r` | yes |
 | Codex's `Hooks need review` | `2\r` | trust all and continue |
+| Codex's `/new`: `Where should the new conversation run?` | `1\r` | current checkout (bot home) |
 | Codex's update offer, `1. Update now` | `1\r` | accept it |
 | `[oh-my-zsh] Would you like to update?` | `n` | they update their own shell |
 | Claude Code's `Teach auto mode about your environment?` | `2\r` | **Not now**: it would write settings of theirs |
@@ -193,7 +195,7 @@ The numbers there are what these menus showed when this was written. Read them
 off the screen in front of you rather than trusting the table: a harness that has
 added an option since has moved them all down one.
 
-Two things to know rather than guess at.
+Three things to know rather than guess at.
 
 Codex's hooks question is not cosmetic. The kit's hook is how the book learns
 which conversation a session is running as, and while that screen is up the
@@ -203,6 +205,10 @@ empty book and nothing says why.
 Codex's trust question applies to the **repository root**, which for a bot means
 the whole bots folder rather than the one bot. That is what they are agreeing to.
 
+Codex's `/new` question (0.156.1 on) is always answered with the current
+checkout, which is the bot home. The kit never makes a git worktree, so
+`2. New worktree` is never the answer.
+
 **Anything you do not recognise: type nothing.** Tell them what is on the
 screen and which tab it is in, and wait. A keypress into a menu you have not read
 is how a harness quits back to the shell.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/rules/finishing.md

@@ -9,6 +9,9 @@ Turn the work into a check you can run. Run it. Read the output.
 Check the thing itself, not a stand-in for it: the file that changed, the
 output the reader will get, the real command against the real tool.
 
+What does not run is checked against the ask: it answers the question, can be
+followed, and its claims hold. Say what stood in, and what it could not show.
+
 Do not say it is done from a plausible diff. Say what the check actually gave,
 failures and empty results included, and what you did not check.
 

package/rules/mail.md

@@ -5,9 +5,9 @@ applies: all
 ---
 
 To reach another session, ask the kit for the road rather than guessing an
-address: `obk message to --bots <bots> --to <bot>/<session>`. It answers with
-the address and the command that carries it. Your bots folder is two levels
-above the folder you start in.
+address: `"${OBK_CLI:-obk}" message to --bots <bots> --to <bot>/<session>`. It
+answers with the address and the command that carries it. Your bots folder is
+two levels above the folder you start in.
 
 Mail is queued, not an interruption. Read it when you finish what you are on.
 

package/rules/scope.md

@@ -16,5 +16,7 @@ When you notice something else worth doing, say so at the end. Doing it is the
 user's call.
 
 Work inside a project of its own (a repo you cloned into your work dir, a
-folder with its own rules) follows that project's rules as well as yours.
-Where the two disagree, say which you followed and why.
+folder with its own rules) follows that project's rules as well as yours, so
+read its AGENTS.md or CLAUDE.md before you start. Where the two disagree, do not
+pick one: tell whoever gave you the work, quote both, and hold that part until
+it is settled.

package/rules/tests-first.md

@@ -5,11 +5,13 @@ applies: code
 ---
 
 A change in behaviour starts with a test that fails for the reason you expect.
-Run it, read the failure, then write the code.
+Run it, read the failure, then write the code. When a failing test really is
+impractical, say why and name the check you ran instead; naming one you will run
+later is not having run it.
 
-The test is written by someone who is not you: a subagent or another session,
-working from the requirement and the public interface. When you can neither
-start one nor reach one, say so and ask.
+Wherever a real test is warranted, it is written by someone who is not you: a
+subagent or another session, working from the requirement and the public
+interface. When you can neither start one nor reach one, say so and ask.
 
 A test that stands in your way goes back to its author with what you think is
 wrong with it. It does not get weakened, skipped or deleted to reach green.

package/skills/obk-arch/LICENSES.md

@@ -8,6 +8,13 @@
 `obk-arch` consolidates material from the sources named in
 [NOTICE.md](NOTICE.md). Their licences are reproduced below in full.
 
+The part on decision records copies words only from Michael Nygard's
+"Documenting Architecture Decisions" (CC0 1.0) and MADR 4.0.0 (taken under
+CC0-1.0, one of its two licences). CC0 waives all rights and asks for no
+notice, so there is nothing to reproduce for them: see
+https://creativecommons.org/publicdomain/zero/1.0/. The other decision-record
+sources in NOTICE.md gave ideas only, and none of their text is used.
+
 ## MIT
 
 The MIT permission notice below applies to the work of each of these copyright

package/skills/obk-arch/NOTICE.md

@@ -4,8 +4,10 @@
 
 # Sources and licences
 
-The skill `obk-arch` was consolidated for this kit from these, all MIT, with
-thanks:
+The skill `obk-arch` was consolidated for this kit from these, with thanks.
+The Cursor pstack and mattpocock/skills material is MIT; for the decision
+record sources, see the note on licences under "Keep a record of a decision"
+below.
 
 - **Cursor pstack**, `architect` with its `runner-prompt`, `design-red-flags`
   and `rationale-template` references. Writing the caller's usage and two or
@@ -114,12 +116,30 @@ thanks:
   the exception for a change that has to happen everywhere; and a prototype
   being throwaway code that answers a question, with the polish skipped on
   purpose.
+- **mattpocock/skills**, `triage` with its `AGENT-BRIEF`, and `to-tickets`
+  further to the above. Handing work over behavioural rather than procedural,
+  what the system should do and not how, the builder exploring fresh and
+  making their own decisions; durable rather than precise, naming types,
+  contracts and behaviours and never file paths or line numbers, because the
+  code moves while the work waits; acceptance criteria that can each be
+  checked on their own; saying what is out of scope so the builder does not
+  gold-plate; the one exception of a prototype's snippet that encodes a
+  decision more precisely than prose (from `to-tickets`); and, before handing
+  a report on, verifying the claim (reproducing it from the reporter's steps
+  and saying whether it was confirmed, failed or lacked detail, a confirmed one
+  making a much stronger brief), searching for it by the concept rather than
+  the reporter's wording to see whether it already exists, checking whether
+  it was turned down before, asking the reporter specific questions rather
+  than for more information, and noting when a piece needs a person's
+  judgement rather than being delegated.
 
 Left behind on purpose: the multi-model arena and its runners, fixed model
 choices, the phase todolist and its ceremony, tracker and pull-request
 machinery, the generated report formats, and the trigger that fires a design
-review on any change crossing a function boundary. This skill is reached for
-when there is a shape to get wrong, not on every change.
+review on any change crossing a function boundary; from `triage`, the labels,
+the state machine, the brief template, the out-of-scope folder, the grilling
+step and the AI disclaimer. This skill is reached for when there is a shape
+to get wrong, not on every change.
 
 What the owner said, and how it shaped this: he asked for a very light part on
 what is wanted and on dividing the work, leaving the details and the tracking
@@ -131,4 +151,92 @@ testable (2026-09-19 18:54, and 2026-09-20 02:21), which is why that part stays
 that the source's strict vocabulary be dropped for plain words (18:50), so the
 list of defined terms is gone and the ideas stay. He did not want a
 blast-radius skill of its own (18:08), so what is kept of it is a short part.
-A small reshaping being part of the change follows PRD 7.3.
+A small reshaping being part of the change follows PRD 7.3. He asked that work
+be handed over by intention, without micro-management or baby steps, with
+only brief research: enough to validate an issue, above all one reported from
+outside, and to triage it (issue #263, 2026-09-24). That is the part on
+handing a piece over, and why its research stops there.
+
+## Keep a record of a decision
+
+Words were copied only from the two sources whose licences waive all rights:
+
+- **Michael Nygard, "Documenting Architecture Decisions"** (Cognitect blog,
+  2011-11-15; CC0 1.0, as stated on the page). The reader who can only
+  blindly accept or blindly change a decision whose reasons are lost; one
+  decision per record, the kinds of decision that earn one (structure,
+  non-functional characteristics, dependencies, interfaces, construction
+  techniques); context as the forces at play, technological, political, social
+  and project local, in tension and described value-neutrally; the decision in
+  full sentences and the active voice, "We will…"; all consequences, not just
+  the positive ones; bullets only for layout, never an excuse for fragments;
+  one or two pages, since nobody reads large documents; records numbered in
+  sequence with numbers never reused; and a superseded record kept, because it
+  is still worth knowing that it was the decision.
+- **MADR 4.0.0** (adr.github.io/madr; MIT or CC0-1.0 at the reader's choice,
+  taken here under CC0). The people who decided and the people consulted as
+  fields of the record, "rejected" among the statuses, consequences written as
+  good and bad, and a way to confirm the decision is kept (MADR's
+  Confirmation, here "Checked by").
+
+Taken as ideas only, in this skill's own words, because their licences do not
+allow the text to be reused (all rights reserved unless noted):
+
+- **Olaf Zimmermann**, ozimmer.ch: "How to create Architectural Decision
+  Records (ADRs) — and how not to", "How to review…", "A Definition of Done for
+  Architectural Decision Making" and "Ten Common Mistakes in Architectural
+  Decision Records". The ways a record goes wrong (only upsides, a straw-man
+  alternative, hidden costs, a sales tone, one option and one time frame, a
+  record carrying a whole architecture or a design, criteria reverse-engineered
+  from the preferred option, a decision section that repeats the title,
+  consequences only for the code); a record for each stage of a staged
+  decision; the confidence level; and the definition of done (evidence, at
+  least two options compared on criteria, challenged and agreed, written and
+  shared, a plan to check and revisit it).
+- **Martin Fowler**, bliki "Architecture Decision Record". Writing the record
+  as a way to bring disagreement into the open; most important first; the
+  confidence and what should trigger a re-evaluation; an accepted record never
+  reopened, only superseded.
+- **AWS Prescriptive Guidance**, "Using architectural decision records…". A
+  rejected record kept with its reason so the topic is not argued again; an
+  accepted record not changed, a change being a new record noted in the
+  record's change history.
+- **Microsoft Azure Well-Architected Framework**, "Maintain an architecture
+  decision record" (Microsoft Learn terms of use). Not editing accepted records
+  but superseding them and linking the two; a record not being a design guide,
+  standing on its own with detail linked; consequences never hidden.
+- **Joel Parker Henderson**, `architecture-decision-record` (CC BY-NC-SA 4.0,
+  which does not fit this use). Dating a fact that will change.
+- **adr-tools** (Nat Pryce; the tool is GPL-3.0, the content it adds to a
+  project CC BY 4.0). Superseding changes only the old record's status, to a
+  link to the new one.
+- **The GDS Way**, "Documenting architecture decisions", and **GOV.UK**,
+  "Architectural Decision Record Framework" (both Open Government Licence
+  v3.0), and **Google Cloud Architecture Center**, "Architecture decision
+  records overview" (CC BY 4.0). Their licences would allow reuse with
+  attribution, but no text of theirs is used. The ideas taken: a title that
+  names the decision rather than the problem, a superseded status with a link
+  to the new record, records kept findable (GDS Way); and a change carrying the
+  previous decision and why it changed (Google).
+
+What the owner said, and how it shaped this part (issue #264, 2026-09-24): a
+record that partly replaces an older one replaces it with a new one, and he
+wanted one good format; then, on the proposed format, "I need full history of
+change history and the context. For the decision made I also need alternative
+listed and why they are not." So a change to any part of an accepted record is
+a new record that replaces the old one whole and restates what still holds,
+the old record changing only its status; the context is given in full; every
+alternative is listed with why it was not chosen; and each record carries the
+dated history of every record it replaces. No source asks for what still holds
+to be restated; that is his rule. Most sources back superseding over amending
+in place; Joel Parker Henderson and Google prefer adjusting the record with
+the history kept, and the GDS Way allows clarifications in place until the
+decision is acted on, which is where the note on drafts and on spelling fixes
+comes from. The format is the default, and a project's own format wins, since
+PRD 7.1 leaves the user free in how they keep documents. Left behind: review
+boards, decision levels and approval steps (the GOV.UK framework, AWS's review
+meetings), which are process; ADR tooling; and the Y-statement and other
+templates.
+
+The three conditions for a lasting record, from mattpocock/skills above, moved
+here from "Write down what you chose" so they are kept in one place.

package/skills/obk-arch/SKILL.md

@@ -3,19 +3,25 @@ name: obk-arch
 description: >-
   Shaping a piece of work before building it: a short note of what is wanted
   and what done means, deciding the shape from the usage and the data with
-  more than one candidate, making the thing runnable and testable so anyone
-  can find out whether it works, and cutting the work into pieces that each
-  end in a check. Use when starting something new, planning a feature, adding
-  a public interface or a new data shape, making a choice that is hard to
-  undo, or when a change is big enough that jumping into the code would settle
-  the shape by accident.
+  more than one candidate, keeping a decision record (ADR) and replacing it
+  whole when the decision changes, making the thing runnable and testable so
+  anyone can find out whether it works, and cutting the work into pieces that
+  each end in a check, and handing a piece to someone else by what is wanted
+  and its boundary, with only the research that confirms and triages it. Use
+  when starting something new, planning a feature, adding a public interface
+  or a new data shape, making a choice that is hard to undo, writing or
+  changing a decision record, handing work to someone else to build, or when a
+  change is big enough that jumping into the code would settle the shape by
+  accident.
 ---
 
 # Shaping work before you build it
 
 Four things: say what is wanted, decide the shape, make sure the thing can be
 started and driven so anyone can tell whether it works, and cut the work into
-pieces that each end in a check. The third is what makes the rest real.
+pieces that each end in a check. The third is what makes the rest real. A
+decision that will outlast the change gets a record of its own. When a piece
+goes to someone else, it goes by its intention; the how is theirs.
 
 None of this needs a particular document, tracker or format. Where a project
 has one, use it; where it does not, a few lines in the right place do the job.
@@ -195,9 +201,8 @@ Where the constraints left only one shape, say that instead: "the only viable
 shape, because...". Name anything a later reader might mistake for an
 oversight.
 
-A lasting record of its own, kept beyond the change, earns its place when all
-three are true: it is hard to reverse, it is surprising without the context,
-and it came out of a genuine trade-off. Miss one and the paragraph is enough.
+Some decisions need more than the paragraph: a record of their own, kept after
+the change. "Keep a record of a decision" below says which ones and how.
 
 ### When to build a throwaway instead of arguing
 
@@ -219,6 +224,167 @@ The observation is the result, not the code. Keep the decision it produced,
 throw the prototype away or park it somewhere clearly marked, and write the
 real thing from the beginning, test first.
 
+## Keep a record of a decision
+
+A decision record (an architecture decision record, ADR) is for someone months
+or years later who meets the decision without its reasons. Without them they
+have two choices: blindly accept it or blindly change it. The record lets them
+do neither. Writing it has a second use: it forces the reasoning into the
+open, where the people involved find out whether they actually agree.
+
+### When one earns its place
+
+All three are true: it is hard to reverse, so changing your mind later costs
+something real; it is surprising without the context, so a reader will wonder
+why it was done this way; and it came out of a genuine trade-off, with
+alternatives that could have been chosen. Miss one and the paragraph from
+"Write down what you chose" is enough. The ones that usually pass are about
+structure, the qualities the thing must have (speed, security, cost to run),
+dependencies, interfaces and how it is built. A proposal that met all three
+and was turned down is kept too, as rejected, with the reason, so it is not
+argued again.
+
+One decision per record. A decision that comes in stages (a stopgap now, the
+real answer later) gets a record for each stage. A record is not a design
+document: component detail, diagrams and code go elsewhere, linked, and the
+record still makes sense without them.
+
+### The default format
+
+Where the project already has a format for its records, use that one. Where
+it does not, this is the default:
+
+```markdown
+# ADR NNNN: <the decision, as a short phrase>
+
+Date: YYYY-MM-DD.
+Status: proposed | accepted | rejected | deprecated | superseded by [ADR MMMM](MMMM-slug.md).
+Decided by: <who>. Consulted: <who, if anyone>. A sentence marked (proposed) is not decided yet.
+Supersedes: [ADR KKKK](KKKK-slug.md). <only when it does>
+
+## Context
+<The full context: the forces at play and the problem. Date any fact that will change.>
+
+## Decision
+<Full sentences: "We will…". All of what holds, including what is carried over
+from a superseded record.>
+
+## Alternatives considered
+- <Alternative>: <what it is; why it was not chosen.>
+
+## Consequences
+- Good: …
+- Bad: … <the cost accepted>
+- Revisit if: … Confidence: <high or low, and why>.
+- Checked by: <a test, a review point, a command; optional>
+
+## History
+- YYYY-MM-DD, [ADR KKKK](KKKK-slug.md): <what it decided or changed, and why>.
+  <one line per earlier record, oldest first; "none" for a first decision>
+```
+
+What each part is for:
+
+- **The title** names the decision, not the problem.
+- **Status.** Proposed while it is being discussed; accepted once the people
+  who decide agree; rejected when it was turned down, kept with the reason so
+  the question is not reopened; deprecated when it no longer applies and
+  nothing replaces it; superseded by the record that replaced it. **Decided
+  by** names who made the call, so a reader knows whom to ask and whose call it
+  was; **Consulted**, whose views were sought.
+- **Context** describes the forces at play: technical, political, social and
+  local to the project, usually in tension with each other, and says so. It is
+  value-neutral: facts, not a case for any option. It is the full context, as
+  a reader of this record alone would need it, not only what changed since the
+  last one. Date a fact that will change (a price, a limit, a version, who is
+  on the team).
+- **Decision** is the response to those forces, in full sentences and the
+  active voice: "We will…". It says all of what now holds, not a repeat of the
+  title.
+- **Alternatives considered** lists every alternative that was on the table,
+  each with what it is and why it was not chosen. The reasons weigh the
+  alternatives against the same forces the chosen one answers. Where the
+  constraints left only one, say "the only viable option, because…"; without
+  the reason that line is not allowed.
+- **Consequences** lists all of them, not just the good ones: what gets
+  easier, what gets harder, the cost accepted, and for everyone the decision
+  touches (whoever runs it, tests it, calls it or pays for it), not only the
+  code. Revisit if names the change in circumstances that should reopen it.
+  The confidence tells a later reader how hard to push. Checked by, where
+  there is one, is how anyone can tell the decision is being kept: a test, a
+  point a reviewer looks for, a command.
+- **History** is the whole story of the decision: one dated line for every
+  earlier record this one replaces, directly or down the chain, oldest first,
+  each with what it decided or changed and why. With the context, it lets the
+  newest record alone tell the full story.
+
+The headings are there to be answered, not filled in. Write in full sentences;
+bullets are for layout, not an excuse for fragments. Keep it short, with what
+matters most first, since a long record goes unread; but short never costs the
+full context, an alternative or a line of the history. What usually makes a
+record long is design detail, and that goes elsewhere, linked.
+
+### Changing a decision
+
+A change to any part of an accepted record is a new record, and the new record
+replaces the old one whole. It carries everything that still holds from the
+old one, restated rather than pointed at, alongside what changed; the full
+context as it now stands; the alternatives, old and new, with why each lost;
+and the history, with a line for the record it replaces. Where it replaces
+more than one, it names each.
+
+The old record keeps its text. Its status alone changes, to superseded by the
+new record, with a link. It stays true to what it says: that this was the
+decision, for that stretch of time, for those reasons.
+
+So a reader never has to put a decision together from several records. The
+newest says all of what holds and how it got there; the older ones say what
+governed the work before.
+
+Not a change: until a record is accepted it is a draft, and a draft is edited.
+A spelling or a broken link fixed without changing what the record says is not
+a change either.
+
+### Where records live
+
+Beside what they are about, in version control, in plain text: one file per
+record, named after the decision, numbered in sequence, and never renumbered.
+A number once used is not used again, even for a rejected record. Where the
+project keeps its records somewhere else, use that. Either way, someone who
+needs a record can find it.
+
+### Before it is accepted
+
+A record is ready to be accepted when:
+
+- there is some evidence the choice will work: a spike, a measurement, the
+  same thing done before, someone who has run it;
+- the alternatives were compared on the forces named in the context: at least
+  two real ones, or the reason there was only one;
+- someone who did not write it has challenged it, and the people who decide
+  agree with the outcome and the reasons;
+- it is written and shared with the people it affects;
+- it is known how to tell it is being kept and when to look at it again.
+
+### Where records go wrong
+
+- **Only upsides.** A reason that only restates the choice ("a queue, because
+  queues are reliable"), and the costs left out or played down.
+- **The straw man.** An alternative that could never have worked, listed to
+  make the chosen one look good.
+- **The sales tone.** Adjectives nobody could back with evidence. Take each
+  one out and see whether the record loses anything.
+- **One option and one time frame.** No real alternative looked for, and only
+  the next few weeks' effects considered.
+- **Criteria after the fact.** The forces chosen to fit the answer, or a
+  record written afterwards to justify a decision already made.
+- **Everything in one.** A record carrying a whole architecture, or a detailed
+  design, instead of one decision.
+- **Only the code's view.** The consequences for the people who run it, test
+  it, call it or pay for it missing.
+- **Edited in place.** An accepted record quietly changed, so nobody can tell
+  what governed the work before, or when it changed.
+
 ## Make it runnable and testable
 
 This is the part that makes an agent able to check its own work at any size
@@ -345,6 +511,51 @@ move the callers over in batches sized by what each batch touches, then delete
 the old form once nothing calls it. If a piece deliberately leaves something
 broken in between, say which piece and for how long.
 
+## Hand a piece over
+
+When someone else will build a piece (a person, another session, a
+subagent), hand it over by its intention and leave the how to them. What goes
+with it:
+
+- **What is wanted, and why.** The note from "Say what is wanted", or where to
+  find it. The why is what lets the builder make the calls you did not
+  foresee.
+- **The boundary.** What is in, what is out, and what it must stay compatible
+  with. Saying what is out keeps the builder from gold-plating the next thing
+  along. A constraint you know of and they could not find belongs here too:
+  that is part of the intent, not a step.
+- **What done means**, as checks that can each be confirmed on their own.
+
+Describe what the thing should do, not how to make it: behaviour, and the
+names, types and contracts it touches, rather than file paths, line numbers or
+a list of steps. The code moves while a piece waits, so paths go stale. A step
+list settles the design before the builder has looked, carries your guesses as
+if they were decisions, and takes away the judgement you handed the piece over
+for. The design, the deeper research and the how are theirs, and so is
+everything in this skill about deciding the shape. One exception: a snippet
+from a prototype that pins a decision more exactly than words can (a state
+machine, a schema, a type), trimmed to the decision and marked as coming from
+a prototype.
+
+Research before handing over goes as far as validating and triaging the
+piece:
+
+- **Is it real?** Above all when someone outside reported it. Reproduce a bug
+  from their steps, or find the behaviour in the running thing or the code,
+  and say what came of it: confirmed and where, not reproduced, or not enough
+  to tell. In the last case, ask the reporter for the specific thing that is
+  missing rather than passing a guess on. A confirmed problem makes a much
+  stronger hand-over than a suspected one.
+- **Is it already there, or already turned down?** Look by what it does, not
+  by the reporter's words, and say where you looked.
+- **Enough to place it**: how much it matters, roughly how big it is, what it
+  touches, and whether it can be handed over at all or needs a person's
+  judgement.
+
+Then stop. Findings by file and line, a proposed fix, or a summary of all that
+in the hand-off message is the builder's work done early, without the
+builder's context.
+
 ## Before you build on it
 
 Find out what the shape breaks elsewhere. Listing the callers is not the job;