@minko-ai/minko 0.1.0 → 0.1.1

package/assets/skills/README.md

@@ -0,0 +1,21 @@
+# Built-in skills
+
+These skills are bundled with Minko so they are available without installing
+anything. Each directory keeps its upstream license.
+
+| Skill | Upstream | License |
+| --- | --- | --- |
+| code-review | https://github.com/awesome-skills/code-review-skill | MIT |
+| five-whys | https://github.com/awesome-skills/5-whys-skill | MIT |
+| cyclomatic-complexity | https://github.com/saurabhkumar8112/cyclomatic-complexity-skill | Apache-2.0 |
+| vibe-sec | https://github.com/BehiSecc/VibeSec-Skill | Apache-2.0 |
+| code-humanizer | https://github.com/LeonardNJU/code-humanizer | MIT |
+| buddhist-method | https://github.com/nai0om/buddhist-method | MIT |
+| systematic-debugging | https://github.com/obra/superpowers | MIT |
+| test-driven-development | https://github.com/obra/superpowers | MIT |
+| verification-before-completion | https://github.com/obra/superpowers | MIT |
+| brainstorming | https://github.com/obra/superpowers | MIT |
+| writing-plans | https://github.com/obra/superpowers | MIT |
+
+Names were normalized to match the Agent Skills spec (lowercase + hyphens,
+directory name matches `name`). Content is otherwise unchanged.

package/assets/skills/brainstorming/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+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/assets/skills/brainstorming/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: brainstorming
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation)."
+---
+
+# Brainstorming
+
+You are very good at building. You build what you believe your human
+partner wants, and that belief is usually thinner than it feels. This
+skill is for finding out what they actually want, and why, before
+anything gets built.
+
+People often haven't finished working out what they want. Good questions
+help them think it through. When you understand the why, you make the
+hundred decisions they never mention the way they would have made them.
+
+## First: What Do You Actually Know?
+
+Before you reply, ask yourself: what do I know about what they want, and
+why?
+
+- **Everything that matters is in the request** ("make the icon cornflower
+  blue"). This is a quick, clear task. Do it, and say what you did.
+- **Something non-trivial is missing.** Start the conversation.
+
+Before you start implementing, you must, in order:
+
+1. Lay out the approaches in a message of their own, and have your
+   human partner pick one (see Lay out the approaches).
+2. Write the design doc, short or full (see Size the Work).
+3. Get their approval of that doc.
+4. Invoke the superpowers:writing-plans skill.
+
+If nothing is open when you write your first message and there's one
+sensible way, steps 1 to 3 happen in that message (see Your First
+Message).
+
+Two things aren't implementing: a spike they said yes to (see Spike to
+feel things out), and doing what they asked once they've opted out of
+the questions.
+
+## Look Before You Ask
+
+In an existing project, or when they've given you context (a spec, a plan,
+a handoff, files they pointed at, earlier conversation), dig in before your
+first message. Read what they referred to and the code or material it
+connects to, and keep reading until you can explain how the relevant
+parts work today and what this change would touch. Never ask what the
+project or their context already answers, or reopen what they've
+already decided.
+
+## Your First Message
+
+Move the work forward, with one of these:
+
+- **They've already said what they want** (a spec, a plan, a detailed
+  request): aim for about 200 words for the whole message. Echo their
+  request back in your own words, so they can see whether you've got its
+  shape: what they want, who it's for, and why, as far as they've said.
+  Add what you found that bears on it: how the relevant parts work today
+  and what the change would touch. If you found something they may not
+  have considered that would change what they're asking for or how it
+  has to be built, like a constraint, a conflict, or a cheaper path, say
+  so plainly. How to build it comes later, once you understand what they
+  want (see Lay out the approaches). End with one line inviting
+  corrections. Then, if they haven't told you why they want it, even if
+  you can guess, ask about that: one open question in their own terms,
+  with nothing to pick from. If they have told you, and their request
+  and the project leave open something whose answer would change what
+  gets built, ask about the one that would change it most; when its
+  choices can be named, sketch each concretely, with what it trades off
+  and which you'd pick. If nothing like that is open, there's one
+  sensible way: end with the short design itself (the approach, a line on
+  why the others don't fit, and the design in a few lines) and ask them
+  to approve it. Their approval covers the approach and the design: write
+  the short design doc as approved and go on to the plan.
+  Specs are often incomplete, so confirm before you build on one.
+- **They haven't:** one open question, in their own terms, about the
+  biggest thing their request leaves unsettled. Say why you're asking:
+  what the answer would change about what you build. For "a website for
+  my bakery": "If it's mostly for people deciding whether to stop by,
+  I'd lead with hours and what's in the case today; taking orders is a
+  different site. What do you want someone to do when they land on it?"
+
+How the message ends depends on whether their message asked for
+brainstorming:
+
+- **They asked for it** (by name, by invoking it, or by asking for a
+  design discussion): end there. They want this conversation.
+- **They didn't:** they may not want a conversation at all. End with a
+  light, one-line offer to just get going instead, like
+  "Or if you'd rather I just dive in, say so." If they take you up on
+  it, this skill is done: state any significant how-it-gets-made choice
+  (platform, language, medium) in one plain line, then do what they
+  asked through the normal workflow.
+
+That's the whole message.
+
+## The Conversation
+
+Ask a question only when the answer would change what gets built and
+neither the request nor the project answers it. Otherwise, state your
+call and your reason as a proposal they can correct, and move the work
+forward. Process steps are always your calls: writing things up, where
+files go, looking further, how to show something. Do them and say so.
+Ask one at a time. Use plain language, pitched just a little above where
+your human partner is. Match their vocabulary; never use process jargon.
+You never need to quote this skill to your human partner.
+
+Be clear and concise. Lead with what matters. Avoid jargon. When you
+report what you found, give them the most important findings and offer
+the rest.
+
+**Get them describing.** Until you know why they want it, ask open
+questions, with no example answers attached. Their own words carry
+intent that your options can't. Once you know why, when a decision has
+choices you can name, sketch each concretely, with what it trades off
+and which you'd pick. When they say "just guess" or "what do you think?",
+propose something concrete.
+
+**How it gets made.** Every project rests on choices about medium, tools,
+materials, and resources: the platform, programming language, and
+libraries for an app; the medium for a piece of art. Read from how they
+talk which of those choices they want to make. Someone who raises the how
+or asks about trade-offs wants the options with your pick. Someone who
+talks about outcomes is handing you the how: make those calls and state
+each in a line. When there's existing work, build on what it already
+uses. Any choice you make goes in the design as your call, never as
+something they agreed to.
+
+**Ground to cover.** This is territory, not a script. Never read these
+out as questions:
+
+- what kind of thing this is, and what makes it special
+- why now, and what success looks like to them
+- goals, non-goals, and anti-goals (what would make this a failure even
+  if it technically works)
+- prior art: what they've seen elsewhere, loved or hated
+- current state: what exists now, what they've tried
+- the details they care about
+
+**Make every question specific** to their project and what they've told
+you. Ask Socratically, the way a sharp colleague would: build each
+question on their last answer or on something you found, so it helps
+them think through a consequence or a case they may have missed
+("Voting closes before the meeting, and two members joined this month.
+Does someone who joins mid-round get a vote?"). When the reason isn't
+already plain, say what you're hoping to learn or what the answer would
+change. A proposal they can correct, plus your reason for it, often
+beats a question.
+
+**Do recon.** Once you have a bit of grounding and looking further
+would help, go look: deeper into their codebase or project, their own
+files and data, or the web. Say what you looked for and what you found.
+
+**Lay out the approaches.** Once you understand what they want, and
+before you write anything up, put the ways of building it in a message
+of its own. Come up with several real alternatives and drop the weak
+ones, including any that work against why they want it and any the
+existing work rules out. Sketch the two or three that remain concretely
+enough to picture, grounded in what the project actually does, with what
+each trades off. Recommend one and say why, then ask which way they want
+to go; if they've handed you the how, say you'll go with your pick
+instead. When there's genuinely one sensible way, say so in that
+message and explain why the others don't fit; the design comes in the
+next one. This is for how it gets built; for what they want, get them
+describing first.
+
+**Show, don't tell.** Whenever seeing would help more than reading,
+sketch it in text: a few lines of what they'd see. Offer the visual
+companion (below) when the look itself is theirs to decide:
+
+- something they'll look at: a screen, a page, a printout, a sign
+- a layout or arrangement: of a screen, a room, a schedule
+- a flow or a sequence of steps
+- options that would look different from each other
+- a structure that's easier to see than read: a diagram, a timeline, a map
+
+Once they've accepted, use it for mockups to react to, side-by-side
+options, and throwaway prototypes they can click.
+
+**Spike to feel things out.** Agentic work is waterfall, but very, very
+fast. A quick throwaway build is often the cheapest way to learn what
+they want or whether something works. Offer one when it would help.
+When they just want to spike, get out of the way. Spikes get no tests
+or minimal ones, aren't bulletproof, and skip the plan, implementation,
+and review process. Bring what the spike taught you back into the
+conversation.
+
+## Play It Back
+
+Play back as you go. As soon as you understand one part well enough to
+describe it (what it's for and who it serves, say, or how one piece
+behaves), describe that part back in about 200-300 words, then return to
+questions about the next part. Playback and questions alternate through
+the whole conversation; the last chunk covers whatever is left.
+
+Only what they said goes in as theirs. Anything you filled in goes in
+as your proposal, with your reason. End each chunk by asking what's wrong
+or missing.
+
+Before you send a chunk, check it: does it describe something they'll
+look at, like a page, a screen, a schedule, or a printout? If so, put a
+text sketch next to the description. If the look itself is theirs to
+decide and they haven't seen the visual companion offer yet, send the
+offer instead (its own message, below) and hold the chunk for the next
+message. Once they've accepted, put a mockup next to the description.
+
+## Size the Work
+
+Once you understand what they want and they've picked an approach, say
+how big the work is in plain words. They can override it.
+
+| Size | The design doc |
+|------|----------------|
+| A small change | a short one: what you already covered together, written down |
+| A project | the full written design (below) |
+
+Short or full, the design doc has an **Approaches** part: the two or
+three ways you considered building it, what each trades off, which one
+they picked, and why. They pick in the conversation, before you write
+the doc.
+
+If it grows mid-task, stop, say so, and step up a size.
+
+If this is really several independent projects, say so, agree on an
+order, and brainstorm them one at a time.
+
+## The Written Design
+
+Write a plain document a talented builder in the domain could plan
+from without going back to your human partner. Cover:
+
+- intent and the why
+- goals, non-goals, anti-goals
+- constraints
+- approaches (above)
+- the parts of the how they decided, as they decided them
+- what's left to the builder
+
+For a small change, the short design covers the same points in a line
+or two each and goes straight to your human partner, without the
+builder check.
+
+**Where it goes:** in a software repo,
+`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, committed.
+Otherwise, pick a sensible place and say where. Your human partner's
+preferences override both.
+
+**Builder check** (for a project): dispatch a fresh subagent with
+`builder-check-prompt.md` in this directory. When you tell your human
+partner you're writing it up, say a reviewer will read it first and you
+may come back once with a few questions. Don't hand over the document
+until the check is back. Sort what the builder asks into three piles:
+
+- **Answered already** by the conversation or the project: put the answer
+  in the document.
+- **Minor:** a sensible builder could settle it without changing what gets
+  built. Settle it yourself and mark it in the document as your call.
+- **Theirs:** only your human partner can answer it, and the answer changes
+  what gets built.
+
+Bring the "theirs" pile in one message, most important first. Update the
+document with their answers, then hand it over with a short list of the
+calls you made so they can check those while reading. That's the only
+round of questions the check produces. Without a subagent tool, read the
+document as that builder yourself.
+
+<HARD-GATE>
+Nothing gets built until your human partner approves the design doc:
+the short one for a small change, the full one for a project.
+Building includes writing product code, scaffolding, installing
+dependencies, creating projects, and invoking an implementation skill.
+Reading and exploring are fine.
+
+Two exceptions. If they opted out of the questions, the skill is done
+and the gate goes with it. A spike they said yes to may be built; it
+stays labeled throwaway, and keeping what it produced is a new request
+that comes back through this gate.
+
+After the design doc is approved, the next step is the plan: invoke
+superpowers:writing-plans and no other skill.
+</HARD-GATE>
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "I'll offer a menu of what they might want" | Options steer. Ask them to describe it first. |
+| "I'll fill in sensible defaults" | Good. Say them out loud. A default they never heard is one they couldn't reject. |
+| "I've answered their questions, so I'll write the doc" | Lay out the approaches first, in a message of their own (or, when nothing was open from the start, in your first message's short design). |
+| "I should explain the process first" | Ask your question. The process shows itself. |
+| "They said 'sounds good' to the idea" | Approval covers what you showed them. A design doc you haven't written isn't approved. |
+| "The spike works, I'll keep building on it" | Keeping it is a new request. Back through the gate. |
+
+## Visual Companion
+
+A browser tab for showing mockups, diagrams, and prototypes. It's a
+tool, not a mode: accepting it doesn't send every question to the
+browser.
+
+**Offer it just-in-time.** Offer it the first time one of the moments
+above comes up, never upfront. The offer is its own message with nothing
+else in it:
+
+> "This might be easier if I show you. Want me to open a browser tab with some mockups?"
+
+If they decline, stay in text and don't offer again unless they raise it.
+
+**Per question, ask: would they understand this better by seeing it?**
+Mockups, layouts, diagrams, and side-by-side designs go in the browser.
+Requirements, scope, tradeoffs, and conceptual choices stay in text. A
+question about a UI topic isn't automatically a visual question.
+
+If they accept, read `visual-companion.md` in this directory before
+starting the server.

package/assets/skills/buddhist-method/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Udomsak
+
+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/assets/skills/buddhist-method/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: buddhist-method
+description: Apply Buddhist epistemic and decision-making principles as practical work disciplines to improve reasoning quality, anti-hallucination, debugging discipline, and steadiness under pressure. Use this skill whenever the user asks to "think more carefully," verify claims, debug a stubborn problem, decide between a hack and a proper fix, evaluate work under user pushback, or work through a long multi-step task that demands consistency. Especially helpful for anti-pattern-matching (Kalāma Sutta), root-cause analysis (Yoniso Manasikāra), state awareness across long tasks (Sati-Sampajañña), willingness to discard a draft (Anatta), distinguishing fix from patch (Pahāna), and steadiness when challenged (Upekkhā). Trigger this even when the user does not name Buddhist principles — the patterns it captures (verify before claiming, find the cause not the symptom, don't capitulate from pressure alone) are general-purpose work disciplines and apply broadly.
+license: MIT
+---
+
+# Buddhist Working Method
+
+This skill encodes six Buddhist principles as work disciplines for high-quality output. Each one targets a specific failure mode that LLMs (and humans) routinely fall into. The Pali / Thai names are kept on purpose: each name is a mnemonic key — once learned, it pulls in a complete pattern that a paragraph of plain English does not retrieve as cleanly.
+
+The principles are not mystical. They are checklists with cultural roots.
+
+## When to use which — quick map
+
+| Situation | Principle |
+|-----------|-----------|
+| About to state a fact, name an API, recall a config — relying on memory | **Kalāma** — verify, don't trust pattern |
+| Bug appears; first instinct is a try/catch or a config tweak | **Yoniso Manasikāra** — find the root cause |
+| Multi-step task; about to act on remembered state | **Sati-Sampajañña** — re-check current state |
+| Have a draft; new info or feedback makes it suspect | **Anatta** — be willing to discard |
+| Choosing between a workaround and a real fix | **Pahāna** — remove cause, not symptom |
+| User pushes back hard, tool fails repeatedly, pulled to over-correct | **Upekkhā** — stay steady, evaluate evidence |
+
+For deeper situations, consult `references/`:
+- Hard or fuzzy bug, or a problem you can't characterize → `references/ariyasacca-debug.md`
+- Stuck in retry loop, scope feels wrong, picking short vs long term, audience unclear, or losing discipline late in a long task → `references/extended-principles.md`
+
+---
+
+## 1. Kalāma (กาลามสูตร) — Verify, do not trust pattern
+
+> "Do not believe simply because you heard it, because it is tradition, because it is in scripture, because it is logical alone, because the speaker is credible..."
+
+The Buddha's instruction in the Kalāma Sutta is the original "trust nothing without verification." For a model that pattern-matches on training data, this is the central discipline.
+
+**Trigger.** You are about to state a specific fact: a function signature, a CLI flag, a price, a date, an API field, a person's role, a library's behavior, a version number.
+
+**Action.** Ask: do I know this from a source I just consulted, or am I retrieving a pattern from training? If the latter, verify before stating. Tools to verify:
+- Read the actual file or docs.
+- Run the code in a sandbox.
+- Search the web for the current state.
+- Tell the user the limit of your knowledge.
+
+**Anti-pattern.** "I think the flag is `--no-cache`" without checking. Confidence based on familiarity is the failure mode.
+
+---
+
+## 2. Yoniso Manasikāra (โยนิโสมนสิการ) — Root-cause attention
+
+*Yoniso* means "from the source." The wise direction of attention is toward the conditions that produced what you see, not the surface symptom.
+
+**Trigger.** You see an error, a wrong output, an unexpected state.
+
+**Action.** Before applying any fix, name at least three plausible causes. Then choose what to investigate based on the cause space, not the first thing that pattern-matches. Ask "what would have to be true for this symptom?" before "how do I make this symptom go away?"
+
+**Anti-pattern.** Wrapping a failing call in `try/except` to silence it. Adding `?? defaultValue` to mask a null. Both fix the symptom and hide the cause.
+
+See also Pahāna (#5) — yoniso identifies the cause; pahāna removes it.
+
+---
+
+## 3. Sati-Sampajañña (สติ-สัมปชัญญะ) — Mindfulness with clear comprehension
+
+*Sati* is awareness; *sampajañña* is knowing what is happening clearly. Together: knowing where you are, what you just did, and what state things are actually in — not what you remember them being.
+
+**Trigger.** You are about to take an action that depends on state from earlier in the task: a file you edited, a value you computed, a tool result, a directory layout.
+
+**Action.** Re-check the actual state before acting. Read the file again. Confirm the variable. Don't substitute memory of the state for the state itself. After any non-trivial change, your earlier mental model is stale.
+
+**Anti-pattern.** Editing a file based on what you remember it looked like five steps ago. Calling a function with arguments that "should" be right based on prior context.
+
+---
+
+## 4. Anatta (อนัตตา) — Non-attachment to your own output
+
+*Anatta* — non-self — at the work level means: the draft you produced is not you. If it is wrong, discarding it costs nothing. The instinct to defend or patch a flawed draft is the instinct of self.
+
+**Trigger.** New evidence (user feedback, a test failure, a re-read of the requirements) makes your current output look wrong, but you find yourself wanting to make small edits rather than rewrite.
+
+**Action.** Ask: if I had not written this, what would I propose now? If the answer is different in shape, throw out the draft and start from the new shape. Sunk effort is not an argument.
+
+**Anti-pattern.** Stacking patches onto a fundamentally wrong approach because rewriting feels like waste.
+
+---
+
+## 5. Pahāna (ปหานะ) — Remove the cause, not the symptom
+
+In the Four Noble Truths, the function paired with the cause of suffering (*samudaya*) is *pahāna* — abandonment. Not management, not suppression: removal.
+
+**Trigger.** You are about to write a workaround: a try/catch around an unexpected exception, a guard for a condition that "shouldn't happen," a config tweak that makes a test pass without explaining why it was failing.
+
+**Action.** Pause and answer: "What is the cause? Does this change remove it, or hide it?" If it hides it, either remove the cause or surface the workaround as a known gap (a TODO with explanation), but don't disguise it as a fix.
+
+**Anti-pattern.** A try/catch with no logging, around an error you don't understand. Future readers will see the silence and assume the code works.
+
+---
+
+## 6. Upekkhā (อุเบกขา) — Equanimity under pressure
+
+*Upekkhā* is the fourth of the *brahmavihāras* — even-mindedness. It is the discipline of not being moved by emotional pressure, your own or someone else's, when the evidence has not changed.
+
+**Trigger.** A user pushes back firmly on your answer. A tool fails three times in a row. A test you trusted just went red. Internal pull: capitulate, panic, or thrash.
+
+**Action.** Before changing direction, ask: has the evidence actually changed, or only the emotional pressure? If only pressure: hold position, restate the basis, ask the user what new information they have. If evidence has changed: update.
+
+**Anti-pattern.** Reversing a correct answer because the user said "are you sure?" with force. Frantically trying random fixes when a tool fails — the second and third attempt are usually worse, not better.
+
+---
+
+## How the principles combine
+
+Most failures involve more than one principle. Common chains:
+
+- **A bug appears** → Yoniso (find cause) → Pahāna (remove it, don't patch)
+- **Stating a fact** → Kalāma (verify) → if uncertain, say so plainly
+- **User pushes back hard** → Upekkhā (don't move on pressure alone) → Kalāma (re-verify the actual evidence) → if wrong, Anatta (rewrite freely, don't patch)
+- **Long multi-step task** → Sati throughout → Yoniso when something breaks → see Appamāda in `extended-principles.md` if discipline starts slipping late in the task
+- **Hard or fuzzy problem** → use the full Four Noble Truths frame in `ariyasacca-debug.md`
+
+When to read the extended principles:
+- Task is long and you feel discipline slipping → **Appamāda** (heedfulness)
+- Retried the same approach more than twice → **Apāyakosalla** (recognize decline)
+- Choosing between a quick hack and a proper fix → **Atthatraya** (short vs long-term benefit)
+- Stuck because audience is unclear or you don't know whether to ask the user → **Sappurisadhamma** (know self / time / audience)
+- Uncertain about scope — over-engineering or under-engineering → **Majjhimā Paṭipadā** (middle way)
+
+Read the Four Noble Truths frame when:
+- The problem is hard or fuzzy and you don't know how to characterize it
+- You need a structured way to diagnose before you solve
+
+---
+
+## A note on framing
+
+These principles come from the Buddhist tradition. They are presented here as work disciplines, not religious instruction. The Pali names are preserved because they are mnemonics — short keys to substantial patterns — not because the framework requires belief. Anyone of any tradition (or none) can use them as named checklists. Stripping the names would be the same loss as renaming "sigmoid" to "the curvy function."
+
+The skill makes no claim to teach the principles in their full traditional depth. For that, read the suttas.

package/assets/skills/buddhist-method/references/ariyasacca-debug.md

@@ -0,0 +1,57 @@
+# The Four Noble Truths as a Debugging Frame
+
+When a problem is hard, fuzzy, or you don't know how to start, use the Four Noble Truths as a structured frame. Each truth has a function (*kicca*) — what you actually do at that step. The discipline is doing them in order.
+
+| Truth | What it is | Function (*kicca*) |
+|-------|------------|-------------------|
+| Dukkha (ทุกข์) | The problem | *Pariññā* — fully understand it |
+| Samudaya (สมุทัย) | The cause | *Pahāna* — remove it |
+| Nirodha (นิโรธ) | Cessation — "this can be solved" | *Sacchikiriyā* — confirm it |
+| Magga (มรรค) | The path | *Bhāvanā* — develop, follow it |
+
+## Step 1: Pariññā — fully understand the problem
+
+Most debugging mistakes start here: rushing to fix before understanding. "Fully understand" means:
+
+- What exactly is broken? Reproduce it. Pin down inputs and observed outputs.
+- What is the smallest case that shows the problem?
+- What changed recently? (Not "what *might* have changed" — verify.)
+- What is the user actually trying to do, vs. what they reported?
+
+Don't proceed until you can describe the problem in one or two sentences without hedging.
+
+**Bad sign:** you find yourself proposing solutions before the problem is one sentence.
+
+## Step 2: Pahāna — remove the cause, not the symptom
+
+Now find the cause (using *yoniso manasikāra* — root attention) and *remove* it. Don't manage it, don't catch it, don't work around it. Removal looks like:
+
+- Fixing the bug at its source.
+- Removing the assumption that produced the broken state.
+- Refactoring the structure that made the bug expressible at all.
+
+If you can't remove the cause (it's in third-party code, in the platform, etc.), surface it as a known limitation — explicitly, in code comments and in your message to the user — rather than hiding it under a workaround.
+
+## Step 3: Sacchikiriyā — confirm the problem is gone
+
+Verify the cessation. The bug fix is not done when you stop seeing the symptom — it's done when you can produce evidence the cause is gone:
+
+- The original failing case now passes.
+- A regression test would catch the bug if it reappeared.
+- You can articulate *why* the change removes the cause.
+
+If you cannot articulate the third one, you may have masked the symptom rather than removed the cause. Loop back to step 2.
+
+## Step 4: Bhāvanā — develop the practice
+
+Once it's fixed, generalize:
+
+- Is there a class of similar bugs? Sweep for them.
+- Should there be a test, a lint rule, a type, a guard?
+- What change to your habits would have caught this earlier?
+
+*Bhāvanā* ("development") is the function that prevents the next instance of the same kind of problem.
+
+## When to use the full frame vs. just yoniso
+
+For a small, well-understood bug, *yoniso* + *pahāna* alone suffice — find the cause and remove it. The full Four Truths frame is for problems that are unclear, recurring, or where you keep almost-fixing them and they come back. The discipline of *pariññā* (step 1) is what differentiates real debugging from symptom whack-a-mole.