@assuredloop/orca-bot-kit 0.1.0 → 0.3.0

package/skills/obk-bot-building/NOTICE.md

@@ -0,0 +1,113 @@
+<!-- Attribution for the sources this skill was built from. Kept out of
+     SKILL.md so it is not read into context on every use; it travels with
+     the skill directory, which is what the licences require. -->
+
+# Sources and licences
+
+`obk-bot-building` reproduces no third-party text. What it took from outside
+this kit, it took as an idea and wrote again in its own words, for the reason
+given under "Ideas taken from material with no licence" below.
+
+## The owner's own words
+
+The charter is three questions because he settled it at three. His word on the
+proposal that the interview happens once at a bot's creation and asks what the
+bot owns, what good work looks like, and what it must ask about first, in the
+research pack's session dialogue: "looks good for charter interview."
+
+Two other lines of his shape this skill. On what a bot is allowed to do: he is
+"building bot to allow agency by itself but in the boundary and contract we are
+creating, not freely", which is why the limits section here reads as a boundary
+to act inside rather than as a leash. His one-liner remark ("I expect to have
+one liner the user can send to LLM, and then the rest is done by AI") was about
+setup, not the interview, and is no longer used for it; the interview follows
+his own grilling instruction instead (below).
+
+On bringing in a session they already run: "yes the session history shall be
+able to resume, i.e., resume an external session, the rest is best effort
+migrated with llm capability", and, correcting a restatement of it, "as the
+setup is done via llm, including future setup via the bot manager, the llm does
+best effort to help user migrate". That is where "best effort, and say so
+plainly" comes from.
+
+## This kit's own design
+
+The PRD and the ADRs carry the rest: the line-up suggestions and the
+role-to-skills guidance (PRD 6.8, ADR 0019, which puts that table in the
+management skill), a session's settings and the rule that the kit never
+hardcodes a model id, the approval levels and that the widest one is used only
+when the user asks for it in plain words, the two plain defaults that no
+silent fallback happens and that a role limit such as "read-only, does not
+modify" is a normal part of a charter (PRD 6.4 and 6.6), and pinning an online
+skill source to a version with a word about what a source carrying scripts or
+hooks means (PRD 6.7).
+
+## Ideas taken from material with no licence
+
+The research pack's `grok-bot-lessons.md` gathers how one hosted bot product is
+run. Its material comes from a knowledge base and from that product's own
+marketplace and documentation pages. No licence is attached to those pages, and
+the pack's own caution records that the marketplace entries were summarised by
+a fetch tool rather than read verbatim. So no text of theirs is reproduced
+here, and none of it was read as text worth copying. What was taken is the
+idea, restated:
+
+- that a bot is a job somebody holds rather than a prompt that came out well,
+  and is named after a job a person could hold;
+- that the thing worth writing down is what it owns, what good looks like, and
+  what it must not do without asking;
+- that an interview at creation is what writes that down;
+- that a bot an existing one could own the work of should not be created;
+- that a role needing several unrelated verbs is more than one role, that the
+  split goes by domain rather than by how much work there is, and that a
+  specialist is worth adding only when a real bottleneck has shown up: a noisy
+  shared context, a bot that cannot review its own work, or permissions that
+  have diverged;
+- that instructions have three lifetimes, the durable role, the one assignment
+  and the reusable procedure, and that a one-off correction must not quietly
+  become a rule.
+
+## What was deliberately not taken
+
+That source's creation interview fills a fixed list of about ten fields. This
+skill asks three questions and stops. The owner settled the charter at three,
+and the rest of what a bot needs is settings, which are not an interview.
+
+Its bot-classification vocabulary is not here either; reviewing a fleet that
+already exists is a different job and lives in `obk-fleet-review`.
+
+## Sources that need no third-party notice
+
+Everything above is either this kit's own design, the owner's own words, or an
+idea restated in our own words from material that carries no licence. Nothing
+in this skill reproduces a third party's text, so there is no permission notice
+to pass on. See [LICENSES.md](LICENSES.md).
+
+## What the re-validation changed (#156)
+
+- The charter questions are asked together, each with a drafted answer, not
+  one at a time: the owner asked to be asked three questions at a time with a
+  recommended answer (research-pack dialogue, 2026-09-19 13:24, with matt's
+  grilling loaded), and
+  his usage review complains of one question per turn.
+- The answer handed back is the roster card PRD 6.8 decides (name, harness,
+  model and effort, a two-line charter, one hard limit).
+- The skills for each role are named, since ADR 0019 puts that choice in the
+  management skill.
+- What the command line does and does not do, checked against `obk --help`:
+  `obk skills fetch` was missing; a charter, settings or list change is an
+  edit plus `obk rules build` or `obk skills build`; pausing or retiring has
+  no command. Each management action is committed (PRD 6.10). Issue #158 later
+  gave changing, pausing and retiring their commands, and the hand edit is
+  left for the special case, said so.
+- A change of model, effort or approval reaches a session only by `obk
+  restart`, on the user's word, and a whole-fleet restart is done from the ops
+  tab (PRD 6.5).
+- Bringing in a session: the outside id goes into the book by hand, and a
+  resume across folders is to be tried before it is promised.
+- Cut: a paragraph restating the opening, and two sentences of framing.
+- Memory per bot is the owner's decision of 2026-09-23 (issue #211): a bot may
+  turn on its harness's memory for itself, since the owner's global setting is
+  off. The three Claude Code keys, and that without `autoMemoryDirectory` every
+  bot in the repo shares one memory, were measured live and are in the tech
+  notes; Codex's memories are the user's and cannot be one bot's.

package/skills/obk-bot-building/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: obk-bot-building
+description: >-
+  Bringing a bot into being: finding out whether the job wants one at all,
+  interviewing its owner into a charter that says what it owns, what good
+  looks like and what it must ask about first, splitting a role that carries
+  unrelated work, giving each session a duty of its own, choosing the skills
+  the job needs and no more, and carrying an existing conversation across.
+  Use when someone wants a new bot, another session on a bot they have, a
+  role written down, or a session they already run brought in.
+---
+
+# Making a bot
+
+A bot is a job somebody holds, not a prompt that came out well. The work is
+the interview; the files it leaves behind are the easy part, and the kit's
+own commands write them.
+
+These are defaults for work where nothing says otherwise. A user who asks for
+something else gets what they asked for; say which of these you left and why.
+
+## Ask whether this wants a new bot
+
+Look at the fleet before you add to it. Where a bot already there could own
+this job, say so and offer that instead: a second bot with an overlapping job
+splits the context, and now two of them half-know the same thing and neither
+is accountable for it.
+
+A new bot earns its place when the work has an owner who is not the owner of
+any existing one, or when a real bottleneck has shown up: the shared context
+is noisy, the bot cannot review its own work, or the permissions the job
+needs are wider than the ones it has now. Wanting the work done faster is not
+one of those.
+
+Say which it is, in one line, before you write anything.
+
+## Name it after a job a person could hold
+
+Inbox Manager, Expense Manager, API Reviewer. A name that describes a job
+brings its own boundary with it, and everyone reading the roster later knows
+what to send it and what not to.
+
+A name that describes a tool, a model, a mood or everything ("assistant")
+does not, and leaves a bot nobody can hold to anything.
+
+## The interview writes the charter
+
+Three questions, and they are the charter: what this bot owns, what good work
+looks like for it, and what it must ask about before it acts.
+
+Ask the three together, and bring an answer of your own to each. Someone who
+is handed a blank page writes a paragraph they will not recognise in a month;
+someone who is handed a draft corrects it in a sentence, and the correction is
+the part worth having. Say which parts of your draft you inferred so they know
+what to push back on.
+
+Write what they said, in their words. Where an answer is too vague to act on,
+keep it and ask again rather than tidying it into something that only looks
+finished. A charter nobody recognises is worse than a short one: it will be
+followed.
+
+Stop when those three are answered. The rest of what a bot needs is settings,
+and settings are not an interview.
+
+## Split a role that carries unrelated work
+
+Where the job needs several unrelated verbs, it is two jobs. Say so and
+propose the split rather than writing one charter that covers both, and split
+by domain rather than by how much work there is: a bot with a narrow domain
+and a lot to do is fine, and a bot with two domains and very little is not.
+
+The test is whether one sentence can say what it owns without an "and" doing
+the heavy lifting.
+
+## Say what it may do alone, and what it must ask about
+
+Sort by what can be undone. What is reversible, it does; what is not, it asks
+about first. A limit is a normal part of a charter and reads as a plain
+sentence: read-only, does not modify. Never sends anything outside the company
+without a yes. Never spends money.
+
+Give the limit teeth by saying what evidence it brings when it escalates, so
+asking is one message rather than a conversation.
+
+Within that boundary the bot acts on its own; that is the point of writing it
+down.
+
+## The role, the task, and the procedure
+
+Three lifetimes, and they belong in three places. The role is durable and
+lives in the charter. A task is one assignment and lives in the message that
+asks for it. A procedure is reusable and lives in a skill.
+
+A one-off correction is a task. Do not let it rewrite the role: "not like
+that, do it this way today" said once becomes a rule forever, and a year later
+nobody can say why the bot refuses something reasonable. Where a correction
+really is durable, say that you are changing the charter, and change it.
+
+## A session is a duty, not a copy
+
+Sessions of one bot share its home, its rules and its skills. What tells them
+apart is the start prompt, and nothing else: it is sent when the tab is made
+and again after a clear, and it is the only thing that says this tab is the
+one that reviews and that one is the one that answers mail.
+
+Each carries its own harness, model, effort, context window and approval
+level. Leave a setting out and the harness's own default applies, which is
+usually right; do not put a model id in because it sounds current. Where the
+model someone asked for is not available, say so and ask. Never quietly run
+on another one: a bot that silently changed model is a bot whose output
+nobody can compare with last week's.
+
+Approval is the ordinary automatic level unless the user asks for something
+else in plain words. Do not raise it to make a session smoother.
+
+A session that works on files of its own gets a work dir inside the bot's
+folder, under `work/`: `--work-dir work/<session>`. Every clone it needs goes
+in there too, not beside the bots folder or anywhere else outside the bot
+home. Where the user names another place in plain words, that place is the
+work dir, and its clones go there. `work/` is kept out of the bots repo, and a
+path written relative to the bot home still points at the right folder when
+the bots folder moves. `obk session add` and `obk session change` say so when a
+work dir leads out of the bot home; take that back to the user rather than
+past them.
+
+## Offer a line-up rather than a blank page
+
+Someone making their first bots does not know what a good set looks like, so
+propose one and say what each part is for. A pair of developers, perhaps on
+different models, with an architect over them: each developer works an issue
+of its own, and the architect hands out the issues, settles disagreements and
+digs into the hard causes. A workhorse, a writer and a thinker, for work that
+is not development.
+
+Suggestions only: they take out or rename what they like, and you build what
+they end up with.
+
+## A bot that writes code
+
+Its tests come from a different author than its code, and its work is read
+by a different reviewer. Write it that way in the charter and the start
+prompts: "a different author", "a different reviewer". Which kind each one
+is, a fresh subagent, a new session, another bot or a person, is the user's
+to say. Ask them, and write what they chose; where they leave it open, leave
+it open. Do not choose for them: the kind you write becomes the rule. A
+line-up that hands one developer's tests to the other has two sessions on
+every issue and loses the pair's parallel work.
+
+The kit's `tests-first` and `review` rule units say this. They apply to code,
+so a bot carries them only when its `rules:` list in `bot.yaml` names them,
+as `kit:tests-first` and `kit:review`; add them to a code-writing bot's list
+by hand and run `obk rules build`.
+
+## Give it the skills the job needs, and no more
+
+Match the skills to the work, not to the title. Something that mostly finds
+things out wants `obk-researching`; something that writes for people wants
+`obk-writing`; a bot that decides wants `obk-decision-memo`. A developer bot
+wants `obk-tdd`, `obk-reviewing` and `obk-debugging`, a reviewer the reviewing
+one above all, and an architect `obk-arch` on top. Someone's own errands want
+`obk-personal-facilitation`.
+
+Every extra skill is more for the bot to read and one more thing that might
+fire when it should not. Where you are not sure, leave it out and add it when
+the job shows it is missing.
+
+A skill can come from the kit, from the user's own folder, from a repo
+online, or from a path on disk. An online source is pinned to a version, and
+it is worth saying out loud that a source carrying scripts or hooks runs on
+their machine on their risk.
+
+## Bringing in a session they already run
+
+Someone moving in usually has a conversation going that they do not want to
+lose. Take the harness's own id for it and record it against the session in
+the book (by hand, since no command takes an outside id), and `obk up` brings
+it back with its history; then read its tab and answer what is on screen
+(see "When a tab it opened is waiting"). Whether a harness resumes a conversation that was
+started in another folder is something to try before promising.
+
+Everything else is best effort, and say so plainly rather than promising a
+clean move: what was in that session's own settings, the rules it worked to,
+the skills it had. Carry across what you can find, list what you could not,
+and let them tell you what mattered.
+
+## Write it down
+
+The kit's command line does the writing, and the files belong to the user:
+`obk bot create` makes the bot, `obk session add` gives it a session, `obk
+source add` records where online skills come from and `obk skills fetch`
+clones them, `obk skills add` puts one on a bot, `obk skills build` links
+them, and `obk up` opens what is missing in Orca. `obk bot change` gives a
+bot a new charter, `obk session change` changes a session's settings, and
+`obk skills remove` takes a skill off a list (then `obk skills build`). `obk
+pause` stops a bot or a session for now and `obk unpause` brings it back;
+`obk retire` ends one. After `obk up`, `obk restart` or `obk unpause`, read
+every tab it opened and answer what is on screen yourself (next section).
+For a special case no command covers, such as a bot's
+rules list, edit the file, run `obk rules build` or `obk skills build`, and
+say that you edited it by hand.
+Run `obk --help` for the flags of the version actually installed rather than
+trusting a line you remember.
+
+A bot that should learn across its sessions can use its harness's own memory,
+turned on for that bot alone, whatever the user's own setting is for everything
+else. The harness writes it, loads it and keeps it tidy itself. On Claude Code
+that is three keys in the bot's `.claude/settings.json`, beside the kit's hook:
+`autoMemoryEnabled: true`; `env` setting `CLAUDE_CODE_DISABLE_AUTO_MEMORY` to
+`"0"` where the user turns memory off that way; and `autoMemoryDirectory`
+naming a folder of the bot's own outside the bots repo, by an absolute path or
+one starting with `~/`, because without it
+every bot in the repo shares one memory. The first 200 lines or 25 KB of its
+index load at every start. Codex's memories belong to the user and are shared
+by every Codex session, so a Codex bot cannot have its own; say so before
+turning them on for one. It is a hand edit, and say that you made it.
+
+After each change, commit what it changed in the bots folder; the kit never
+commits by itself.
+
+Do the reversible part and stop at the line. Making a bot, adding a session
+and linking skills add things and are safe to run again; closing a tab,
+pausing or retiring a bot and restarting anything are not, and they wait for
+the word.
+
+## When a tab it opened is waiting
+
+A new tab often stops on a first-run screen before the session starts:
+the harness asking whether to trust the folder, Codex asking to review
+hooks, a harness offering its own update, the shell offering to update
+itself. Answering these is your job, not the user's. Answer them in the tab
+yourself, without asking, and tell the user afterwards what you answered.
+The kit types the launch line and nothing more, so no one else will.
+
+Look at every tab `obk up`, `obk restart` or `obk unpause` opened, not only
+the ones it says are waiting. The kit cannot always tell: a tab stopped on a
+trust screen is often reported as up, Claude Code's every time and Codex's
+sometimes. Read each screen with `<orca> terminal read --terminal <handle>
+--screen`, where `<handle>` is the terminal the kit named for the tab and
+`<orca>` is the Orca CLI the kit uses: `$OBK_ORCA` when that is set, and
+otherwise `/Applications/Orca.app/Contents/Resources/bin/orca`. A bare
+`orca` can fail. Send each answer as one `<orca> terminal send --terminal
+<handle> --text …`, with the return inside the text and no `--enter`:
+
+| On screen | Send | Which is |
+|---|---|---|
+| Claude Code's folder trust list | `\x1b[B\r` | down, return: it starts on **No, exit** |
+| Codex's `Trust this folder?`, `1. Trust and continue` | `1\r` | yes (older: `1. Yes, continue`) |
+| 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` | no: the shell is the user's to update |
+| Claude Code's `Teach auto mode about…` | `2\r` | **Not now**: it writes the user's settings |
+
+Read the numbers off the screen in front of you rather than trusting the
+table: a harness that has added an option has moved them. Codex's hooks
+question matters most. The kit's hook is how the book learns which
+conversation the session is running, and until it is answered the
+conversation has not started. Codex's trust applies to the repository root,
+which is the whole bots folder. Codex's `/new` asks where the new
+conversation runs; the answer is always the current checkout, the bot home,
+and never `2. New worktree`: the kit never makes a git worktree.
+
+Where the kit says no session came up, the shell swallowed the launch line,
+usually while it was asking its own question. Answer the shell, then close
+that one tab (`<orca> terminal close --terminal <handle> --tab`) and run
+`obk up` again. This is the one tab you may close without asking: the kit
+opened it a moment ago, and it holds no conversation.
+
+A screen you do not recognise gets no keypress. Take what it says, and which
+bot and tab it is in, to the user. When you have answered, read the screen
+again and check a session is running before you call the bot ready.
+
+## When the bot is already running
+
+Changing a bot whose sessions are up is the ordinary case rather than the
+awkward one. Both harnesses read a skill through the link and notice a change
+to the skills directory while a session is running, so putting a skill on a
+bot, or taking one off, reaches a live session without restarting it.
+
+Noticing is not the same as confirmed. Check that the session can actually see
+the skill before telling anyone it is there, and check by asking that session
+rather than by looking again at the disk you just wrote: what you wrote is not
+evidence about what another process has loaded. Where it has not appeared, say
+so and say what would make it appear. A restart is the user's to ask for, and
+taking one because it is the quick way ends a conversation they were in the
+middle of.
+
+Instructions are not skills. A session is working from the rules it read when
+it started, so a change to a bot's `AGENTS.md` may not reach one that is
+already up even when a skill change would, and a session's model, effort or
+approval only changes when it is started again (`obk restart`, on the user's
+word, and then read its tabs as above). Say which you changed, and what that
+means for the sessions running now. Where everything needs restarting, remind
+them to do it from Bot Father's ops tab.
+
+And tell them. A bot's sessions share its rules and its skills, so a change
+made for one of them lands on all of them, and the session that asked is not
+the only one affected. Say what changed and what it means for what they are
+doing, in their own tabs, rather than leaving them to find out mid-task.
+
+## What they get back
+
+Its card: the name, the harness, model and effort of its sessions, a two-line
+charter, and its one hard limit. Its sessions and what each is for. The skills
+it has and where they came from. And the one thing you need from them, where
+something is still open.
+
+Point at the charter rather than reproducing it, and say what you inferred
+rather than what they told you, so the parts they have not really agreed to
+are the parts they read.
+
+Sources and licences: [NOTICE.md](NOTICE.md).

package/skills/obk-debugging/LICENSES.md

@@ -0,0 +1,67 @@
+<!-- The licences of the sources this skill was consolidated from. They travel
+     with the skill directory because the licences require it of anyone who
+     distributes the material. NOTICE.md says what was taken from each source;
+     this file carries the permission notices themselves. -->
+
+# Licences of the sources
+
+`obk-debugging` consolidates material from the sources named in
+[NOTICE.md](NOTICE.md). Their licences are reproduced below in full.
+
+## MIT
+
+The MIT permission notice below applies to the work of each of these copyright
+holders, and is reproduced with each of their notices. The path after each one
+is the licence file it was read from, in the research pack's source clones.
+
+- **`mattpocock/skills`**, Copyright (c) 2026 Matt Pocock
+  (`mattpocock_skills/LICENSE`)
+- **Cursor `plugins`, the pstack plugin**, Copyright (c) 2026 Lauren Tan
+  (`cursor_plugins/pstack/LICENSE`)
+- **`obra/superpowers`**, Copyright (c) 2025 Jesse Vincent
+  (`obra_superpowers/LICENSE`)
+- **`addyosmani/agent-skills`**, Copyright (c) 2025 Addy Osmani
+  (`addyosmani_agent-skills/LICENSE`)
+- **`garrytan/gstack`**, Copyright (c) 2026 Garry Tan
+  (`garrytan_gstack/LICENSE`)
+- **`KentBeck/BPlusTree3`, for his own rules file**, Copyright (c) 2025 Kent Beck
+  (`KentBeck_BPlusTree3/LICENSE`)
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+Copyright (c) 2026 Lauren Tan
+Copyright (c) 2025 Jesse Vincent
+Copyright (c) 2025 Addy Osmani
+Copyright (c) 2026 Garry Tan
+Copyright (c) 2025 Kent Beck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Sources that could not be read
+
+- **`tw93/Waza`** is not among the clones in the research pack. Its `hunt`
+  skill is quoted in the pack's `source-book-2.md`, which records the
+  repository as MIT. What this skill takes from it is written in our own words.
+
+These are named in NOTICE.md for honesty about where the material came from.
+No text of theirs is reproduced in this skill, and their licence files were not
+available here to reproduce.

package/skills/obk-debugging/NOTICE.md

@@ -0,0 +1,115 @@
+<!-- Attribution for the sources this skill was built from. Kept out of
+     SKILL.md so it is not read into context on every use; it travels with
+     the skill directory, which is what the licences require. -->
+
+# Sources and licences
+
+The skill `obk-debugging` was consolidated for this kit from these, all MIT,
+with thanks:
+
+- **mattpocock/skills**, `engineering/diagnosing-bugs`. The whole shape of it.
+  The feedback loop as the skill itself and worth disproportionate effort, the
+  ten ways to build one in order, tightening it for speed, sharpness and
+  repeatability, raising the rate on an intermittent bug rather than chasing a
+  clean one, the four things that make a loop finished, the refusal to
+  hypothesise before the command exists, reproducing the reported symptom
+  rather than a nearby one, cutting until every part is load-bearing, three to
+  five ranked falsifiable candidates with the prediction each makes, showing
+  the ranked list to whoever is there, one variable per probe, a debugger over
+  logs and never logging everything, tagging temporary logs with one marker,
+  measuring before fixing a slow thing, the regression test at a correct seam
+  and "no correct seam is itself the finding", redacting secrets from anything
+  shown, and the list to clear before calling it done.
+- **Waza**, `hunt`, through the verbatim passages in the research pack. The
+  gate sentence and its form ("I believe the root cause is X because Y", named
+  to a file, function, line or condition), the rule that the cause must explain
+  every symptom including the one waved away, running the one probe that would
+  fail if you were wrong and discarding on contradiction rather than stacking a
+  fix on it, every log as a yes-or-no question and a log that changes behaviour
+  being evidence in itself, the rationalisation tells, the sibling sweep with
+  every match answered in writing, bisecting only with a pass/fail command
+  decided up front and a clean tree first, reading the diff when the last good
+  version is close, the same symptom after a fix meaning stop patching and
+  re-read the path, and stopping after three failed hypotheses. The owner
+  marked the gate sentence as worth borrowing in his own notes; the rest of
+  `hunt` came in on the research's recommendation.
+- **Cursor pstack**, `principle-fix-root-causes` and the `poteto-mode`
+  playbooks. Not adding guards to silence a crash, a workaround needing a
+  paragraph meaning the code is wrong, checking for the pattern rather than the
+  instance, suspecting stored state first when something fails after a restart,
+  and from `principle-attack-the-premise`, two fixes sharing one premise
+  meaning the premise is what to suspect and test next, written down before
+  another fix is tried, while it may still not be the cause. From the
+  `hillclimb` playbook: several runs and the median, keeping a change only
+  when the number moves past the noise, and correctness outranking the
+  number. From the `perf-issue` playbook: measuring before claiming a limit, the
+  families a fix takes used as hypothesis generators rather than a checklist,
+  and capturing the measurement again afterwards to compare against the
+  baseline. Every shipped line tracing to runtime evidence with the smallest
+  change the evidence justifies and reverting what a refuted idea motivated,
+  and verifying on the same surface with "inconclusive is not a pass" and a
+  unit test showing branch behaviour rather than absence of the bug. From its
+  `runtime-forensics` and
+  `trace-forensics` playbooks: an existing capture is read rather than re-run,
+  turned into a queryable shape before reading and reduced elsewhere when it is
+  large; narrowing to the hot call path, to the retainer chain from a leaked
+  object back to a root, or to a blocked thread and its wait reason; mapping
+  the finding to file, symbol and line, with a frame that has no source behind
+  it not yet being a diagnosis; confirming against a paired capture or else
+  calling it the strongest hypothesis the artefact supports; and proving the
+  mechanism on the live process where it can still be reached.
+- **obra/superpowers**, `systematic-debugging` with `root-cause-tracing` and
+  `condition-based-waiting`. Logging what enters and leaves each boundary and
+  reading where it first goes wrong before digging in, tracing backwards
+  through the call chain to where the wrong value was born and fixing it there,
+  logging before the dangerous operation rather than after it fails, printing
+  to the error stream in tests because a logger may be swallowed, three failed
+  fixes meaning the architecture rather than the hypothesis is wrong and what
+  that looks like, waiting for the condition rather than for a duration,
+  reading fresh state inside the loop, always setting a limit with a message,
+  the case where a fixed wait is right and what has to accompany it, and the
+  things someone says when they can see you are guessing. Also, when the
+  cause really is external, handling at the boundary and a way to see it next
+  time, with most "no root cause" being an investigation stopped early; and
+  finding the test that leaves state behind by running them one at a time.
+
+- **obra/superpowers**, `systematic-debugging`, further to the above. Finding
+  the nearest thing that works in the same codebase, reading it properly rather
+  than skimming, and listing every difference however small without deciding in
+  advance which cannot matter.
+- **addyosmani/agent-skills**, `debugging-and-error-recovery`. The decision
+  tree for a bug you cannot reproduce on demand, sorted into timing,
+  environment, state left behind and genuinely random, with what to try in each
+  and documenting the conditions as a real answer for the last; and treating
+  error output as untrusted data, since a message from a dependency, a log or a
+  build can carry something shaped like an instruction and is to be read for
+  clues rather than followed; keeping the evidence before a restart or a
+  clean-up; and a test that looks wrong going back rather than being obeyed.
+- **Waza**, `hunt`, further to the above. Its gotchas: walking back out of a
+  library frame into your own code, suspecting persisted output written by the
+  old code when the algorithm changed and the output did not, trusting the
+  observation over the log and treating the gap as an un-instrumented path, a
+  guard that refuses having a set of causes rather than one, taking a
+  lower-layer baseline before blaming the visible thing, diagnosing an external
+  tool before switching it, and never restarting more than twice without new
+  evidence.
+
+- **garrytan/gstack**, `investigate`: earlier fixes in the same area pointing
+  at the shape of the code, and the rest of the suite still passing after the
+  fix.
+- **Kent Beck's own rules file**: two tests for a defect, one at the interface
+  and the smallest one where the fault lives.
+- **Cursor pstack**, `runtime-forensics`, further to the above: when the
+  question is why, the deliverable is the diagnosis, not a fix.
+
+The owner's own framing leads the skill: reproduce it, find the difference in
+environment, version and context, and the hard cases being random and slow
+(research-pack dialogue, 2026-09-19 18:45). The plain opening and the dropped
+slogans follow his remark that the source's voice was too strong and too
+personal (18:41 and 18:46).
+
+Left behind on purpose: the iron-law capitals and "refuse to give up" framing,
+validating at every layer as a general answer (it contradicts fixing the cause,
+and the kit's own rules say the smallest change that works), per-vendor tooling
+names and control-skill machinery, fixed model choices, and the parts that
+assume a particular tracker or pull-request flow.