@assuredloop/orca-bot-kit 0.1.0 → 0.2.0

package/skills/obk-teach/NOTICE.md

@@ -0,0 +1,65 @@
+<!-- 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-teach` was consolidated for this kit from this, MIT, with
+thanks:
+
+- **Cursor pstack**, `teach`: explaining what a thing is, how it works and why
+  it is built that way, at the person's pace, with understanding rather than
+  any change as the goal; choosing the few things they should walk away with
+  from why they are asking and what they already know, read from the
+  conversation rather than quizzed, skipping what they plainly know and putting
+  the depth where their question is; getting oriented by reading the thing
+  before explaining it; keeping another source's confidence language intact
+  because its hedges are findings rather than style; starting with a plain
+  definition in general terms with the thing's common name, then tying it to
+  the case in front of them, then building through how it works to the deeper
+  reasons and the edge cases; explaining each part so the idea clicks (the
+  problem it solves and how it actually works) with listing functions and
+  constants called out as reference rather than teaching; walking through what
+  happens as the person does the thing when that is what makes it land; the
+  smallest complete answer first, a sentence or two rather than a dense
+  paragraph, then stopping and adding layers when asked, and never a wall of
+  text; keeping it a conversation rather than a lecture, with no quizzes, no
+  asking them to say it back, no pacing theatre, and none of the framing labels
+  (the key insight, at its core, the part worth slowing down on, the tricky
+  part, where it gets interesting); stopping where you would pause and letting
+  them respond, and delivering cleanly with the offer at the end when nobody is
+  there; showing rather than only telling by opening the diff, the code or the
+  debugger; building a picture up diagram by diagram, each redrawing the last
+  and adding one part so the reader watches the system assemble, with the
+  worked example of drawing A to B, then redrawing with C, then the return
+  edge, and a single all-at-once diagram named as a reference rather than
+  teaching; matching the medium to the idea, a diagram for a flow or structure
+  where labels carry the meaning and a rough spatial sketch with few short
+  labels for layout, overlap or a before and after; and its writing guidance
+  (plain spoken English as to a colleague, tight rather than
+  terse, the concrete mechanism rather than a metaphor or a framing, short
+  sentences with full stops preferred to commas, one or two commas and clauses
+  split rather than piled up, one
+  name per concept kept throughout, no em dashes, no mirror sentences and no
+  tidy closers, the parts of the skill being directions rather than labels to
+  print, and the reply being the explanation itself rather than a report about
+  it). Its worked density example is not carried; the rules it illustrates
+  are.
+
+Made generic, which is what the owner asked for. The original is built on top
+of two other skills it invokes by name, and a kit skill carries what it needs
+rather than depending on another being loaded (ADR 0009); here getting
+oriented is part of the work, and where the reasons are the point that is
+named as its own kind of digging without requiring a particular skill. Its
+named image-generation tool is likewise described by what it produces rather
+than by the tool.
+
+One departure: the original keeps itself from being invoked on its own with
+`disable-model-invocation: true`, which is not portable frontmatter (ADR 0009
+and PRD 7.2: these run on purpose, never automatically). The description
+carries that instead: the phrases that ask for it, and the note that answering
+a question in passing is not this.
+
+A second departure: the original forbids quizzing outright. Here someone who
+asks to be tested on it is asking for something else, and that is theirs to
+ask for; the defaults do not stop a user asking for what they want.

package/skills/obk-teach/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: obk-teach
+description: >-
+  Explaining a piece of work so someone actually understands it: choosing the
+  few things they should walk away with, starting from what the thing is
+  before how it works, giving the smallest complete answer and stopping,
+  building a picture up one part at a time, and letting them steer. Run it when
+  you are asked to: "explain this to me", "help me understand X", "what is this
+  actually doing", "walk me through it". Answering a question in passing is not
+  this; this is for when someone has asked to be taught something.
+---
+
+# Explaining something so it lands
+
+The goal is that they understand it. Not that you have covered it, and not
+that you change anything.
+
+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.
+
+## Decide what they should walk away with
+
+A few things, not everything. Choose them from why they are asking. About to
+change it, reviewing it, chasing a bug in it, new to it: each wants a different
+few. Choose them from what they already know, too, and read both from the
+conversation.
+
+Skip what they plainly know already. Put the depth where their question is,
+not where the subject happens to be interesting.
+
+## Get your bearings first
+
+Read the thing before explaining it: the code, the change, what it touches.
+Where the reasons are the point, why it is shaped this way or where a number
+came from, that is its own kind of digging. It is worth doing properly rather
+than guessing at plausibly.
+
+When you are carrying someone else's findings into your explanation, you can
+reword freely with one exception: leave their hedges alone. "Probably" and
+"we could not find out" are findings, not style, and flattening them into
+certainty is how a guess becomes a fact.
+
+## Start with what it is
+
+Name the thing and say what it is, in general terms, the way someone who knew
+the subject would say it out loud. Use its ordinary name if it has one.
+Then tie it to the case in front of them: *in this codebase, we use it to...*
+Then build: how it works, then the deeper reasons, then the edges.
+
+For each part, explain the idea so it clicks: the problem it solves, and how
+it actually works. Listing the functions and the constants is reference, not
+teaching. Where following what happens as they do the thing is what makes it
+land, walk through that.
+
+Give the smallest complete answer first, a sentence or two rather than a dense
+paragraph, and then stop. Add the next layer when they ask for it. A wall of
+text is not generosity; it is a way of not choosing.
+
+## Keep it a conversation
+
+Offer to go deeper or move on, and follow where they go. Do not quiz them to
+find out what they know; read that from the conversation. Do not ask them to
+say it back to prove it landed. Someone who asks to be tested on it is
+asking for something else, and that is theirs to ask for.
+
+Do not narrate the teaching. No announcing that something is the key insight,
+the tricky part, the thing to hold onto, or where it gets interesting. No
+writing "pause" and no summary of what you are about to say. Say the thing
+instead. If it matters, it will show.
+
+Where you would pause, stop and let them answer. If nobody is there to answer,
+deliver it cleanly in one go and put the offer to go further at the end.
+
+## Show it, and build the picture up
+
+Open the code, the change, the running thing, when that is faster than
+describing it.
+
+Draw when a picture beats words. For anything with three or more moving parts,
+do not draw one diagram with all of them. Draw a short series, each one
+redrawing the last and adding a single part, so they watch it assemble. To
+explain something passing from A to B to C: draw A to B; redraw and add C;
+redraw and add what comes back. One all-at-once diagram, especially saved for
+the end, is a reference rather than teaching. A single simple point needs no
+picture at all.
+
+Match the medium to the idea. A flow or a structure where the labels carry the
+meaning is a diagram. Something spatial is a sketch, roughly drawn with a few
+short labels: a layout, an overlap, a before and after.
+
+## How it reads
+
+Plain spoken English, the way you would explain it to a colleague standing
+next to you. Tight, not terse: cut the filler, keep the part that makes it
+click. State the mechanism rather than a metaphor for the mechanism.
+
+Short sentences, full stops rather than commas. One or two commas at most; when
+the clauses pile up, split them. No em dashes. Give each idea one name and keep
+that name. Avoid the tidy closer, "and the rest follows", "it all falls out".
+Avoid the mirrored sentence that says the same thing twice in opposite order.
+
+What comes back is the explanation itself, never a report about having
+explained it. The parts of this skill are directions to you, not labels to
+print: do not echo them as headings.
+
+Sources and licences: [NOTICE.md](NOTICE.md).

package/skills/obk-why/LICENSES.md

@@ -0,0 +1,42 @@
+<!-- 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-why` 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.
+
+- **Cursor `plugins`, the pstack plugin**, Copyright (c) 2026 Lauren Tan
+  (`cursor_plugins/pstack/LICENSE`)
+
+```
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+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.
+```

package/skills/obk-why/NOTICE.md

@@ -0,0 +1,74 @@
+<!-- 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-why` was consolidated for this kit from this, MIT, with thanks:
+
+- **Cursor pstack**, `why` and its `references/epistemics.md`: investigating
+  the motivation behind code as distinct from what it does; the opening
+  observation that code does not carry its own motivation, so the why lives in
+  commits, reviews, tickets, documents and conversations, all incomplete and
+  sometimes missing, and that pretending otherwise produces confident-sounding
+  guesses that mislead; parsing the target and the kind of question, and
+  stating your reading when the target is vague rather than asking; anchoring
+  in concrete code first (the paths and line ranges, the symbols, the recent
+  commits, the review discussion attached to them) before looking anywhere
+  else; the categories of place a reason lives and what each is uniquely good
+  at, with source control best for the rationale captured
+  at review time, the tracker best when the reason is external to engineering,
+  long-form documents where the thinking predates the code, real-time chat for
+  deliberation that never reached a document and most valuable when the written
+  trail is thin, and runtime records best for defensive code such as guards,
+  retries and limits; running them in parallel, one per source; documenting the
+  null rather than skipping the search, with an unavailable source flagged as a
+  gap and a skip allowed only when provably rather than probably irrelevant;
+  recency bias as the named failure, since the current shape is usually the
+  accretion of earlier decisions; the five confidence tiers with their
+  examples and their phrasing (written down, converging evidence, inferred
+  with the chain made explicit, speculative with alternatives beside it, and
+  unknown stated precisely as what was searched); the words that carry a
+  citation with them, each needing its source immediately beside it, and the
+  calibration check that the code is never evidence for its own intent; the
+  embedded-hypothesis trap, where a question arrives with its answer attached
+  and confirming it is the cheap and wrong move; surfacing both sides when two
+  sources disagree rather than picking the tidier story; the output sections
+  including one line per source consulted covering the empty and skipped ones;
+  and turning the findings into a preserve, change, avoid and risk constraint
+  set when the question precedes a change.
+- The same skill's `references/sources/code-archaeology.md`. Its pitfalls: the
+  squash merge that flattens a branch's steps, the commit message that calls a
+  behaviour change a small refactor so the diff has to be read instead, the
+  pattern copied without its reason so the place it started is the one to
+  investigate, and the automated change that carries no motivation at all.
+
+One thing in the squash paragraph is ours rather than the source's. That a
+squash merge loses the branch's commits is the source's pitfall; what is added
+here is where the reason then is (the argument that moved a value is worth
+more than the value it landed on) and the instruction to cite the change that
+did the thing rather than the one that delivered it. That came out of an
+acceptance run of this skill, which traced a constant's history correctly but
+cited the squash merge for a value that the merge had never held.
+
+Made generic, which is what the owner asked for. The original discovers hosted
+integrations and maps them to seven fixed categories, spawns investigator and
+synthesizer subagents on named models, and keeps four reference files of
+prompts and per-source playbooks. This version names the kinds of place a
+reason lives and says to use the ones the project actually has, keeps the
+confidence tiers and the null-result discipline in the skill itself, and leaves
+how the work is divided up to whoever is doing it.
+
+One departure: the original keeps itself from being invoked on its own with
+`disable-model-invocation: true`, which is not portable frontmatter (ADR 0009
+and PRD 7.2: these run on purpose, never automatically). The description
+carries that instead: the phrases that ask for it, and the note that it is not
+something to start unasked before an ordinary change.
+
+Further from `references/epistemics.md`: not turning an absence of evidence
+into evidence of absence, naming who could answer what nobody recorded, a
+write-up with no gaps being suspicious, and the words that claim certainty
+without a source. From `references/sources/code-archaeology.md`: searching the
+history for the change that added or removed an exact string, and the tests as
+a place the reason is encoded. The original's "source control is always
+available" is not carried: a project may keep no history this bot can read.

package/skills/obk-why/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: obk-why
+description: >-
+  Finding out why code is the way it is, and saying how sure you are: anchoring
+  the question in the actual lines, following the history and the discussion
+  around them, looking wherever else this project records its reasons, and
+  separating what someone actually wrote from what you worked out and what
+  nobody recorded. Run it when you are asked to: "why is this like this", "why
+  did we pick that", "where did this number come from", "find out why before
+  you touch it". Not something to launch on your own before an ordinary change;
+  where the shape puzzles you and nobody asked, say so and offer it.
+---
+
+# Why it is like this
+
+Code does not carry its own motivation. You can read what it does; you cannot
+read why it exists. That lives in commits, reviews, issues, documents and
+conversations, all partial, some missing, some wrong. Pretending otherwise
+produces a confident answer that sends someone the wrong way.
+
+So the work is two things: find what was actually recorded, and be honest
+about the difference between that and what you have pieced together.
+
+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.
+
+## The question, and the lines it is about
+
+Work out what is being asked about and what kind of answer would settle it: the
+reason for a design, a trade-off, an edge case that forced something, an
+outside constraint, or something that looks dead. Where the target is vague,
+say which reading you took in a line and carry on, so it can be corrected
+without a round trip.
+
+A question often arrives with its answer attached: "why do we do it this way,
+is it for performance?" Treat the guess as one candidate and check it like any
+other. Confirming it because it was offered is the cheapest way to produce a
+wrong answer that everyone then believes, because it carries your name as well
+as theirs. Where the evidence supports it, say so and cite it; where it does
+not, say what the evidence supports instead.
+
+Then anchor it in the code before going anywhere else: the files and the line
+ranges, the names that matter, the last handful of changes that touched them,
+and the review or discussion those changes belong to. Everything after this
+hangs off that anchor, and an investigation that never had one tends to answer
+a question nobody asked.
+
+Where the project keeps its history, start there. Who last touched these
+lines and in what change; the whole life of the file, including through
+renames; what the change said about itself; and whatever discussion is attached
+to it, which is usually where the reason actually is.
+
+## Then look where else this project keeps its reasons
+
+Different reasons live in different places, and which of these exist varies by
+project. Use the ones it has:
+
+- **The history and its discussion**, where the project keeps them. Best for
+  the reason given at the time by the person doing it, under review. For a
+  number or a string, search the history for the change that added or removed
+  that exact text; it goes straight to the moment it arrived.
+- **The tests**: their names and cases often encode the edge case that forced
+  the code.
+- **Whatever tracks the work**: issues, tickets, a board. Best when the reason
+  came from outside engineering: a customer, a deadline, a rule.
+- **Longer documents**: a design note, a page somewhere. Best where the
+  thinking was written out before it became code.
+- **The conversation**: wherever the team talks. Best for the deliberation
+  that never made it into anything durable, and most valuable exactly when the
+  written trail is thin.
+- **Whatever records what actually happened in use**: errors, metrics, logs.
+  Best for defensive code: a guard, a retry, a limit, a special case usually
+  exists because something happened.
+
+Look in them in parallel where you can, one pass per source with its own
+question. Where a source does not exist or you cannot reach it, that is a
+finding: write down that you could not look there. Skipping something because
+it is probably irrelevant is not the same as it being provably irrelevant, and
+the first one belongs in the write-up as a gap.
+
+Watch for the newest change looking authoritative. The shape you are asking
+about is usually the accumulation of several decisions, and the most recent one
+often only moved something that an earlier one put there. Trace back until the
+reason appears or the trail ends.
+
+And watch for a history that has been flattened. Where a project collapses a
+branch into a single change when it lands, that change shows the end state and
+none of the steps: a value that was set, argued over and moved twice appears to
+have arrived at its final form in one go. The steps are still there, on the
+branch or in the discussion attached to it, and that is usually where the
+reason is. The argument that moved it is more informative than the number it
+landed on. Cite the change that actually did the thing, not the one that
+delivered it.
+
+Three more things mislead in a history. A change that describes itself as a
+small refactor sometimes carries a deliberate change of behaviour, so read the
+diff rather than the message. A pattern may have been copied without its
+reason, so where the same shape appears in several places, find where it
+started and investigate that one instead. And automated changes (dependency
+bumps, backports, anything raised by a bot) usually carry no motivation at
+all, so they are not where the reason is.
+
+## How sure you are
+
+Every claim sits in one of these, and it is said differently in each. Keeping
+them apart is most of the value of the whole exercise.
+
+- **Someone wrote it down.** An explicit statement answering the question: a
+  change description saying what it fixes, a comment saying why the number is
+  what it is, a document choosing between two options. Say it plainly, present
+  tense, and cite where it came from.
+- **Several things point the same way.** Nothing states it, but the evidence
+  converges. Say so, and name the pieces: "the evidence points to X. The
+  change is labelled performance, the tests added all exercise very large
+  inputs, and the surrounding work touches the same path."
+- **You worked it out.** A reasonable reading with nothing explicit behind it.
+  Hedge it, and show the chain: given this and this, that seems likely, because
+  of this. The reader needs to know it is your interpretation.
+- **You are guessing.** Plausible, thin evidence, other explanations fit as
+  well. Say it is a guess and put the alternatives next to it.
+- **Nobody recorded it.** You looked and it is not there. This is a real
+  result and worth saying precisely: not "we could not find out" but what you
+  searched and how, and who could answer it (the author, whoever owns the
+  product). The specific version tells the next person where not to look
+  again. Nobody mentioning a concern is not evidence there was none. A
+  write-up with no gaps in it at all is itself worth a second look.
+
+Where two sources disagree, surface both. The issue says the work was for a
+customer's compliance requirement and the change says it was tidying up an
+area: both can be true, since one motivated the work and the other is how the
+author framed it, or one of them can simply be wrong. Picking whichever makes
+the tidier story is how the disagreement gets buried. Put them side by side
+with their citations and let the reader decide.
+
+Do not launder one of these into another. An inference stated in the voice of
+a citation is the failure this whole skill exists to prevent. Some words carry
+a citation with them ("because", "the reason is", "was designed to", "fixes",
+"the team decided"), and each one needs its source immediately beside it or a
+hedged word instead. Words that claim certainty without one ("obviously",
+"clearly") go.
+
+Check it from the other side before you finish: the code is evidence of what
+exists and what changed, and never on its own evidence of why. Reading the
+change that set a limit to 6000 and the one that moved it to 6500 establishes
+both of those values, and you need that to cite the right change. Neither of
+them tells you what the author was trying to do. So where a claim about
+motivation rests on the code alone (the name of the function, the shape of the
+branch, the value of the constant), that is the thing being explained, not the
+explanation of it.
+
+## What you hand back
+
+- **The question**, as you understood it.
+- **The code**, so the reader knows what is being explained.
+- **What was actually recorded**, cited.
+- **What follows from it**, marked as reasoning.
+- **Other explanations that fit**, where more than one does.
+- **What nobody wrote down**, with what you searched.
+- **Where you looked**, one line per source, including the ones that held
+  nothing and the ones you could not reach, with the reason.
+- **How sure you are overall**, in a line.
+
+When this is the prelude to changing the thing, finish by turning the reasons
+into constraints on that change: what must be preserved and why, what is free
+to change, what to avoid doing, and what is risky because the original reason
+may still apply. That is what makes the history useful rather than merely
+interesting.
+
+Sources and licences: [NOTICE.md](NOTICE.md).