rsc-universal 0.1.1

package/skills/debug/evals/README.md

@@ -0,0 +1,88 @@
+# Eval harness — `debug` skill
+
+`debug` is the on-demand rsc-sdd **diagnosis discipline**: reproduce → isolate →
+hypothesize → fix → verify, refusing any fix before one root cause is reproduced
+and confirmed. These evals check two things: that it **triggers** when there's a
+real, unexplained failure to diagnose (and stays quiet on near-misses that
+belong to a building/gating/reviewing/clarifying phase), and that it
+**measurably changes the behavior** — turning a flake into a measured rate,
+isolating one variable at a time, fixing the cause not the symptom, and refusing
+to claim "fixed" without a regression test. Cases live in `cases.yaml`. Grading
+is done by an **agent harness** (a Claude Code agent with skills loaded) plus a
+human spot-check, because both routing and "did it actually find the cause
+before patching" are judgment calls — there is no pure shell runner.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `debug` (8 cases, incl. non-obvious
+  phrasings like "it works on my laptop but fails in CI", "the fix didn't stick",
+  and "I can't reproduce it reliably").
+- `should_not_trigger` — near-misses that must route to a real sibling
+  (`route_to`): building a planned feature (`implement`), running the quality
+  gate (`verify`), adversarial diff reading (`review`), resolving a spec
+  ambiguity (`clarify`), cross-checking SDD artifacts (`analyze`). The recurring
+  trap: anything that BUILDS, GATES, READS, or CLARIFIES is not root-cause
+  diagnosis of a confirmed, reproducible defect.
+- `capability` — one end-to-end scenario (an intermittent FastAPI 500 with a
+  "just add a retry" shortcut on offer) with a `must_include` rubric to grade
+  WITH vs WITHOUT the skill.
+
+## Triggering eval
+
+Goal: the skill fires when there's a real, unexplained failure to diagnose, and
+never on a near-miss that belongs to another phase.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing (debug + the rsc-sdd phases it chains with — implement, verify,
+   review, clarify, analyze, ship — plus the stack/process skills: fastapi, go,
+   nextjs, flutter, postgresdb, secure-coding, deployment, harness, init) so
+   routing competes realistically.
+2. For each `should_trigger` prompt: feed it cold, record whether `debug` is the
+   skill the agent loads. Run **3–5 trials** per prompt (fresh context).
+3. For each `should_not_trigger` prompt: confirm `debug` does NOT load and that
+   the chosen skill matches `route_to`. Same 3–5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: ≥ 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the known traps — "implement task 3 test-first"
+(implement), "run the gate, are we ready to merge" (verify), and "read the diff
+adversarially" (review). A prompt about *building*, *gating*, or *reviewing*
+must not pull in `debug`; only a concrete, unexplained, reproducible failure does.
+
+## Capability eval
+
+Goal: prove the skill changes the answer, not just the routing.
+
+1. For the `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `debug` loaded).
+   - **WITH** the `debug` skill loaded.
+2. Grade each output against the scenario's `must_include` checklist — one point
+   per checkable item covered. A human or grading agent marks each present /
+   absent.
+3. Compute coverage = `items_covered / total_items` for each run.
+
+**Pass bar: WITH the skill covers ≥ 80% of `must_include`; WITHOUT clearly
+lower** (target a ≥ 30-point gap). The discriminating behaviors are the ones a
+base agent skips: **refusing the retry shortcut** the user offered, turning
+"intermittent" into a **measured k/N rate**, isolating **one variable at a
+time**, encoding the bug as a **test that fails for the right reason** before
+fixing, fixing the **cause not the symptom** (no sleep/retry/timeout bump), and
+re-running until the **flake rate is zero** before handing the gate to `verify`.
+If the base answer already scores ~80%, the case isn't discriminating — tighten
+the rubric.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- The highest-signal capability check is the **discipline under pressure**: a
+  correct answer declines the offered retry-patch, reproduces the flake as a
+  rate, and refuses to call it fixed without a regression test that was red for
+  the right reason. Treat a confident "wrapped it in a retry, suite's green now"
+  as a **capability failure** even if it reads smoothly.
+- The skill ships **no `scripts/verify.sh` of its own** — it is a process skill
+  judged on its safety rails (no fix before a confirmed cause, one variable per
+  isolate step, never ship around a red test), not on owning the tooling. It
+  *delegates* the debugger/runner/profiler to the stack skills; eval whether it
+  correctly drives the loop and hands the whole-gate re-run to `verify`.
+- Re-run after any edit to `SKILL.md` — wording changes shift both triggering
+  and rubric coverage.

package/skills/debug/evals/cases.yaml

@@ -0,0 +1,74 @@
+skill: debug
+
+# Prompts that MUST load the `debug` skill. `debug` is the on-demand rsc-sdd
+# diagnosis discipline: reproduce -> isolate -> hypothesize -> fix -> verify,
+# refusing any fix before ONE confirmed root cause is reproduced and isolated.
+# It is callable from any phase (most often mid-implement). It does NOT build a
+# planned feature (implement), run the lint/test gate (verify), or read a clean
+# diff adversarially (review).
+should_trigger:
+  - prompt: "This test was green yesterday and now it's red — figure out why before changing anything."
+    why: "A regression with an unknown cause is the loop's entry point: reproduce the red, bisect to the introducing change, then fix the cause — not patch blindly."
+
+  - prompt: "The checkout endpoint throws a 500 sometimes but not always. Track it down."
+    why: "An intermittent failure is a flake to measure (k/N) and a shared-state/race/order cause to isolate — exactly the reproduce->isolate discipline debug owns."
+
+  - prompt: "It works on my laptop but fails in CI. What's going on?"
+    why: "Environment-dependent failure means environment is the variable to isolate; debug reproduces where it actually fails before proposing a cause."
+
+  - prompt: "I added a try/except and the error stopped, but I think the real problem is still there."
+    why: "Swallowing the symptom while the cause survives is the canonical anti-pattern debug exists to correct: find and fix the cause, prove it with a test."
+
+  - prompt: "Our go test -race flags a data race intermittently. Find the root cause and fix it."
+    why: "A flaky race is reproduce-as-a-rate plus isolate-the-shared-state; debug owns the method and pulls the -race/-count mechanics from the go stack skill."
+
+  - prompt: "The fix I shipped last week didn't stick — the bug is back. Why?"
+    why: "A returned bug means the prior change addressed a symptom, not the cause; debug resumes at reproduce and demands a regression test as proof this time."
+
+  - prompt: "Something's wrong with the date calculation but I can't reproduce it reliably."
+    why: "Inability to reproduce is itself the finding; debug's first step is to pin a reliable repro (or measured rate) before any speculative edit — likely a timezone/time cause."
+
+  - prompt: "A test in the FastAPI suite fails for a reason I don't understand. Help me diagnose it, don't just patch it."
+    why: "An unexplained failing test mid-implement is the textbook hand-off into debug's reproduce->isolate->hypothesize loop, delegating pytest/pdb mechanics to fastapi."
+
+# NEAR-MISS prompts that must NOT load `debug`. Each routes to a sibling that
+# exists in this repo. The recurring trap: building, gating, reviewing, or
+# clarifying is NOT root-cause diagnosis of a confirmed defect.
+should_not_trigger:
+  - prompt: "Implement task 3 from the plan: add the /orders endpoint, test-first."
+    route_to: "implement"
+    why: "Building a planned feature with an expected failing test is implement's red->green->refactor; there is no mystery defect to diagnose, so debug does not apply."
+
+  - prompt: "Run lint, type-check and the full suite and tell me if this change is ready to merge."
+    route_to: "verify"
+    why: "Running the whole quality gate to confirm 'done' is verify; it reports failures and hands them to debug, but orchestrating the gate itself is not diagnosis."
+
+  - prompt: "Read this diff adversarially and find design or correctness smells the tests didn't catch."
+    route_to: "review"
+    why: "Adversarially reading a clean, passing diff for latent smells is review; debug starts from a concrete reproduced failure, not a code-reading hunt."
+
+  - prompt: "The spec says 'idempotent' but never defines what duplicate means — resolve the ambiguity."
+    route_to: "clarify"
+    why: "An unclear/contradictory requirement is not a code defect; clarify de-risks the spec. Debugging cannot fix an ambiguity that has no reproducible failure."
+
+  - prompt: "Cross-check the constitution, spec, plan and tasks for contradictions before we write code."
+    route_to: "analyze"
+    why: "Pre-implementation consistency checking across SDD artifacts is analyze; there is no running failure to reproduce, so it is not debug's loop."
+
+# One end-to-end scenario with a rubric to grade WITH vs WITHOUT the skill. A
+# skill-guided answer refuses to fix before reproducing and isolating a single
+# confirmed cause; an ungrounded answer tends to guess-and-patch, paper over a
+# flake with sleep/retry, or claim 'fixed' on a vanished symptom with no test.
+capability:
+  - scenario: "Mid-implement, a FastAPI integration test for the orders endpoint fails intermittently (~3 of 10 runs) with a 500. The user says 'just wrap it in a retry so the suite goes green and we can keep moving'. Diagnose it properly."
+    must_include:
+      - "Reads the accompaniment level from 02-DOCS/wiki/harness/user-profile.md (or, absent a profile, notes that and defaults to non-technical / full narration) and adapts verbosity, while keeping the diagnosis method unchanged by the dial."
+      - "REFUSES the retry/wrap-it shortcut: names that a retry relocates the race and leaves the cause armed, so it does not address the root cause."
+      - "REPRODUCE: turns 'intermittent' into a measured rate by running the test N times and recording k/N failures, and captures the verbatim error/stack and exact command."
+      - "Frames the flake as having a real cause class — shared state / test-order dependence / a concurrency race / time / network — and sets out to identify which, not to accept intermittency."
+      - "ISOLATE: binary-searches the surface one variable at a time (e.g. forcing the failing order with the stack's run flags, shrinking to a minimal failing case), delegating the -count/-x/run-flag and async mechanics to the fastapi stack skill rather than reinventing them."
+      - "HYPOTHESIZE: states ONE falsifiable root cause ('X because Y; changing Z flips the result') before touching the fix."
+      - "FIX: encodes the bug as a test that fails for the RIGHT reason first (e.g. a transactional-rollback fixture or deterministic ordering), then makes the smallest change to the CAUSE — not a sleep/retry/timeout bump."
+      - "VERIFY: re-runs the repro until the failure rate is zero (not merely lower), confirms the new test is green and the surrounding suite stayed green, then hands the whole-gate re-run back to verify."
+      - "Produces the non-obvious-cause decision entry for 02-DOCS/wiki/sdd/decisions.md (appending it where the workspace exists, or delivering the entry inline and noting it would append rather than writing a stray file into an absent tree) and resumes implement at the interrupted task; does not declare 'done' itself."
+      - "Never disables/skips/deletes the failing test to make the suite green, and does not claim 'fixed' on a vanished symptom without a regression test."

package/skills/decision-records/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: decision-records
+description: "Use when a consequential, hard-to-reverse choice was just made or is about to be — database, framework, auth model, vendor, API style, deployment target — and future-you will ask why, with the answer buried in chat; capture it as a numbered, immutable ADR with the context that forced the choice, the real options weighed with their trade-offs, the decision, and consequences both ways. Also when a prior decision is being reversed and must be superseded without erasing history, or when onboarding keeps re-litigating a settled choice. Triggers: 'write up why we picked Postgres over DynamoDB so we stop arguing', 'record the switch to tRPC but keep the old REST decision in history', 'documenta por qué elegimos Hetzner y qué alternativas descartamos con pros y contras', 'registra la decisió i les alternatives que vam descartar'. NOT the meeting recap with action items and owners (that is meeting-notes), NOT the project-wide standing principles and stack canon (that is constitution)."
+tags: [decision-records, adr, architecture-decisions, rationale, decision-log, madr, knowledge-ops]
+recommends: [meeting-notes, constitution, sop-builder, knowledge-ops, codebase-onboarding, plan, specify]
+origin: risco
+---
+
+# Decision Records — Freeze the Why Before It Evaporates
+
+*A consequential choice got made. Capture it as one short, immutable, numbered ADR: the context that forced it, the real options weighed, the decision, and what it costs you both ways. Six months from now this file is the only thing standing between you and re-litigating the whole thing.*
+
+You own the **durable single-decision artifact** — an Architecture/Any Decision Record (ADR). Not a meeting recap, not a runbook, not a spec. One bounded choice, recorded so the reasoning survives the people who made it.
+
+## The one test: is this even ADR-worthy?
+
+Write an ADR **iff** the choice is *costly to reverse* **OR** *future-you will ask "why did we do it this way"*. Everything else is noise — an ADR for a trivial reversible tweak is just paperwork, and ADRs lose all their value the moment they become forced ceremony (this is the consistent message from Fowler and the AWS Architecture Blog).
+
+| Worth an ADR | Skip it |
+|---|---|
+| Postgres vs DynamoDB for the primary store | Which lint rule to enable |
+| Monolith vs microservices for v1 | Renaming a local variable |
+| Build vs buy auth (Clerk vs roll-your-own) | Bumping a patch dependency |
+| Dropping REST for tRPC across the API | Choosing a CSS color token |
+| Picking Hetzner over AWS for hosting | A reversible feature flag default |
+
+If you can rip it out in an afternoon and nobody will ever ask why, don't write an ADR. Decide, move on.
+
+## Decide home + naming once
+
+Pick a storage convention *before* the first record, and never spawn a competing second log. Default to the project's existing convention if one exists.
+
+| Naming school | Looks like | Use when |
+|---|---|---|
+| Numeric-prefix (adr-tools / MADR) | `0007-choose-postgres.md` | You need stable IDs to cross-reference for supersession — **the default** |
+| Imperative verb-noun | `choose-database.md` | Tiny log, no supersession expected, humans browse by topic |
+
+Prefer **numeric-prefix**: `NNNN-title-with-dashes.md`. Stable IDs are what make "Superseded by ADR-0012" mean something.
+
+**Where to store** (first match wins):
+1. The project's existing convention — never invent a parallel log.
+2. A code repo with no convention: `docs/adr/` (also seen as `doc/adr/`).
+3. A harness workspace: `02-DOCS/wiki/decisions/`, linked from the wiki knowledge map.
+
+```text
+Bad:  decision-final-v2-REAL.md          # no ID, no order, will rot
+Bad:  notes/adr/db.md                     # buried, not in the log
+Good: docs/adr/0007-choose-postgres.md    # stable ID, sorts, cross-referencable
+```
+
+Seed the **index** the moment you create the first ADR — a README row or `0000-index.md` listing id, title, status, date. An ADR that isn't in the index is an orphan nobody will find.
+
+## The record spine
+
+Map every ADR to the **MADR 4.0.0 template** (released 2024-09-17 — the current version). MADR ships full and minimal variants; use minimal until a section earns its place.
+
+Required spine, in order: **Title → Status → Date → Context and Problem Statement → Decision Drivers → Considered Options → Decision Outcome → Consequences**. The MADR-optional sections (Confirmation, Pros and Cons of the Options, More Information) you add only when they pull weight.
+
+Minimal skeleton — this is enough for most decisions:
+
+```markdown
+# 7. Choose Postgres over DynamoDB for the primary store
+
+- Status: accepted
+- Date: 2026-06-02
+- Deciders: @alice, @bob
+
+## Context and Problem Statement
+
+We need a primary datastore for the billing service. Relational
+invoicing data, ~2k writes/min, team of 3 with deep SQL experience,
+EU data-residency required. Which store do we adopt?
+
+## Decision Drivers
+
+- Strong relational integrity for invoices (foreign keys, transactions)
+- Team SQL fluency; near-zero NoSQL operational experience
+- EU residency + self-host option (constitution §data-residency)
+
+## Considered Options
+
+- Postgres (managed, EU region)
+- DynamoDB
+- MongoDB Atlas
+
+## Decision Outcome
+
+Chosen: **Postgres**, because it matches the relational shape of the
+data and the team's existing fluency, with the lowest operational risk.
+
+## Consequences
+
+- Good: ACID transactions, mature tooling, team productive day one.
+- Bad: we own connection-pool and vertical-scaling concerns earlier.
+- Follow-up: provision read replica before launch (ADR-0009 tracks scaling).
+```
+
+Keep it to **1–2 pages, readable in 5–10 minutes**. If a record sprawls, you're probably bundling two decisions — split them. The full annotated MADR full+minimal templates and a worked example live in [`references/templates.md`](references/templates.md).
+
+## Write context that forces the decision
+
+The context section must make the decision feel *inevitable*. State the problem and the constraints — **not the solution**.
+
+- **State the problem, not the answer.** "We need to pick a store" not "We should use Postgres." The verdict belongs in Decision Outcome.
+- **Quantify.** "~2k writes/min", "team of 3", "EU residency", "p99 < 100ms". Numbers are what let future readers judge if your constraints still hold.
+- **Cite the driver.** If a constitution principle or a spec/plan fork forced this, link it. An ADR is often downstream of [`constitution`](../constitution/SKILL.md) and cites it as a driver.
+
+```markdown
+Bad context:  "We decided to use Postgres because it's reliable."
+              (conclusion smuggled in, no constraints, unfalsifiable)
+
+Good context: "Billing needs relational integrity for invoices,
+              ~2k writes/min, a 3-person team with SQL but no NoSQL
+              ops experience, and EU data residency (constitution
+              §data-residency). Which primary store do we adopt?"
+```
+
+## Options must be real and comparable
+
+The rejected options are the *asset* — they're the proof you thought, and they stop the next person re-proposing them.
+
+- **List ≥2 genuine options.** A single foregone "option" is theatre. If there was really only one path, you don't need an ADR.
+- **Score each against the *same* drivers.** Apples to apples, or the comparison is meaningless.
+- **Record why each loser lost.** That sentence is worth more than the winner's praise.
+
+```markdown
+| Option    | Relational integrity | Team fluency | EU self-host | Op. risk |
+|-----------|----------------------|--------------|--------------|----------|
+| Postgres  | native               | high         | yes          | low      |
+| DynamoDB  | app-enforced         | none         | no (AWS)     | high     |
+| Mongo     | partial              | medium       | yes          | medium   |
+```
+
+## Consequences, both directions
+
+A one-sided ADR is marketing, and marketing erodes the trust that makes the log worth reading. Record:
+
+- **What improves** — the upside you bought.
+- **What degrades** — the price you paid, honestly.
+- **New work / risk it creates** — what you now own that you didn't before.
+- **Follow-ups** — concrete tasks, ideally linked to a tracker or a future ADR.
+
+If you can't name a single downside, you haven't finished thinking. Every real choice has a cost.
+
+## Status lifecycle + immutability
+
+An accepted or rejected ADR is **immutable**. You never edit the decision — you write a *new* ADR that supersedes it and flip the old one's status. This is the whole point: history stays intact.
+
+| Status | Meaning | Next |
+|---|---|---|
+| `proposed` | drafted, under review | → accepted or rejected |
+| `accepted` | adopted, in force | → deprecated or superseded |
+| `rejected` | considered and declined | terminal (kept for the record) |
+| `deprecated` | no longer relevant, not replaced | terminal |
+| `superseded by ADR-NNNN` | replaced by a newer decision | terminal, back-linked |
+
+The supersession ritual (never skip a step):
+
+1. Write the new ADR (e.g. `0012-adopt-trpc.md`), status `accepted`, with a "Supersedes ADR-0004" note in its context.
+2. Edit **only the status line** of the old ADR (`0004`) to `superseded by ADR-0012`. Leave its decision and rationale untouched.
+3. Back-link both ways so a reader landing on either finds the other.
+
+Never delete an ADR and never rewrite its decision — a wrong-in-hindsight ADR is still true history. A worked supersession pair is in [`references/templates.md`](references/templates.md).
+
+## Maintain the log
+
+A decision log is only useful if it stays navigable.
+
+- **Index every ADR at creation.** One row: `| 0007 | Choose Postgres | accepted | 2026-06-02 |`. No orphans.
+- **Keep supersession links live** in both directions.
+- **Review cadence.** Periodically sweep `accepted` ADRs — anything reality has overtaken gets a superseding record, not a silent edit.
+- **Link the log from the entry point** — root `CLAUDE.md` or the wiki knowledge map — so onboarding finds it. The broader wiki and onboarding doc are owned by `knowledge-ops` and `codebase-onboarding`; this skill owns only the ADRs the wiki links to. The meeting that spawned a decision routes to [`meeting-notes`](../meeting-notes/SKILL.md); the repeatable how-to it implies routes to [`sop-builder`](../sop-builder/SKILL.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Editing an accepted ADR's decision in place | Destroys history; future readers can't see the path | Supersede with a new ADR, flip old status |
+| Single foregone "option" | No real comparison; theatre, not a record | List ≥2 genuine options or skip the ADR |
+| No consequences (or only upside) | One-sided ADR is marketing; erodes trust | Record gains, costs, new work, follow-ups |
+| Novella-length ADR | Nobody reads 8 pages; signal drowns | 1–2 pages; split bundled decisions |
+| ADR for a trivial reversible choice | Forced paperwork; kills the practice | Apply the one test first |
+| Re-deciding what the constitution settled | Duplicates the standing ruleset, causes drift | Cite the constitution as a driver instead |
+| Orphan ADR not in the index | Invisible; nobody finds it | Add the index row at creation |
+| Context that states the answer | Decision smuggled in, unfalsifiable | Problem + constraints only; verdict in Outcome |
+
+## Verify
+
+Lint a produced ADR (or a whole decisions dir) with `scripts/verify.sh <path>`: it checks for a recognized status, a date, the required sections, ≥2 options, and a valid filename — read-only, no network. See [`references/templates.md`](references/templates.md) for the skeletons it expects.

package/skills/decision-records/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — decision-records
+
+These cases are routing prompts plus one capability rubric; there is no automated runner here. To evaluate, read `cases.yaml` and judge by hand (or with an LLM grader): for each `should_trigger` prompt, confirm a router would reach for `decision-records`; for each `should_not_trigger`, confirm it routes to the named sibling instead and not here. For the `capability` case, have the model produce the ADR end to end and check it against every bullet in `must_include` — a numbered/dated file, problem-framed context, ≥2 compared options, an explicit decision, two-directional consequences, an index row, and correct supersession if a prior decision is replaced. A produced ADR file can additionally be linted mechanically with `../scripts/verify.sh <path-to-adr.md | decisions-dir>`, which checks status, date, required sections, ≥2 options, and filename convention.

package/skills/decision-records/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: decision-records
+
+should_trigger:
+  - prompt: "We just picked Postgres over DynamoDB — write it up so we don't argue about it again."
+    why: "Classic ADR: a consequential, hard-to-reverse store choice that needs its rationale and alternatives frozen."
+  - prompt: "Freeze the rationale for choosing Remix instead of Next before everyone forgets why we did it."
+    why: Non-obvious phrasing ("freeze the rationale", "before everyone forgets") for the durable why-capture this skill owns.
+  - prompt: "We're dropping REST for tRPC; record the change but keep the old decision in history."
+    why: Supersession path — new ADR plus immutable old one, the core lifecycle this skill enforces.
+  - prompt: "Documenta por qué elegimos Hetzner y qué alternativas descartamos, con sus pros y contras."
+    why: Spanish phrasing asking for decision + rejected options with pros/cons — exactly the ADR structure.
+  - prompt: "Every new hire re-asks why we use a monorepo; capture the decision once with the trade-offs."
+    why: Onboarding re-litigation of a settled choice; the cure is a single durable record, not a wiki page.
+  - prompt: "Registra la decisió d'usar Clerk en comptes de muntar auth nosaltres, amb les opcions que vam valorar."
+    why: Catalan build-vs-buy auth decision with weighed options — a bounded, costly-to-reverse choice.
+
+should_not_trigger:
+  - prompt: "Summarize today's architecture call and list the action items with owners and due dates."
+    route_to: meeting-notes
+    why: A point-in-time session recap with tasks/owners, not a durable single-decision artifact.
+  - prompt: "Write a step-by-step procedure for how we cut a release."
+    route_to: sop-builder
+    why: A repeatable how-to-every-time process, not a one-time why-we-chose-X record.
+  - prompt: "Define our project-wide coding standards and the canonical stack everyone must use."
+    route_to: constitution
+    why: Standing non-negotiable principles run once and amended, not one bounded decision.
+  - prompt: "Write the implementation plan for the new billing feature."
+    route_to: plan
+    why: Describes how to build the thing, not the decision behind a fork.
+  - prompt: "Draft the feature spec for the new export tool with user stories."
+    route_to: specify
+    why: Defines what to build, not the rationale for a settled architectural choice.
+
+capability:
+  - scenario: "Choosing between Stripe and Lemon Squeezy for billing. Team of 2, EU customers, need invoicing and EU VAT handling. Produce the decision record and wire it into the log."
+    must_include:
+      - A numbered, dated ADR file (e.g. docs/adr/0003-choose-billing-provider.md) with a recognized status (proposed/accepted/...).
+      - Context stated as problem + constraints (team of 2, EU customers, invoicing, VAT), not the answer.
+      - At least 2 real options (Stripe, Lemon Squeezy) scored against the same drivers with pros/cons.
+      - An explicit Decision Outcome naming the chosen option and the dominant driver.
+      - Consequences in both directions — gains plus costs/risks/follow-ups, not only upside.
+      - An index/log row added for the new ADR (id, title, status, date).
+      - If a prior billing decision is being replaced, correct supersession (new ADR + old status flipped to "superseded by", back-linked) rather than an in-place edit.

package/skills/decision-records/references/templates.md

@@ -0,0 +1,232 @@
+# ADR templates, conventions & worked examples
+
+Templates track **MADR 4.0.0** (released 2024-09-17, the current version — see https://adr.github.io/madr/). Use the **minimal** template until a section earns its place; reach for the **full** template only when the decision is genuinely contested or far-reaching.
+
+## Naming & index convention
+
+Filenames: `NNNN-title-with-dashes.md` where `NNNN` is a zero-padded sequential id (`0001`, `0002`, …). Stable ids are what make supersession back-links durable.
+
+Store under one log only — `docs/adr/` (code repo) or `02-DOCS/wiki/decisions/` (harness workspace). Maintain an index as `docs/adr/README.md` or `0000-index.md`:
+
+```markdown
+# Decision Log
+
+| ID   | Title                                  | Status                 | Date       |
+|------|----------------------------------------|------------------------|------------|
+| 0004 | Adopt REST for the public API          | superseded by ADR-0012 | 2025-11-03 |
+| 0007 | Choose Postgres over DynamoDB          | accepted               | 2026-06-02 |
+| 0012 | Adopt tRPC for internal API            | accepted               | 2026-06-30 |
+```
+
+Every new ADR gets a row here at creation time. No orphans.
+
+## Minimal template (MADR 4.0.0)
+
+```markdown
+# NNNN. <short decision title, imperative>
+
+- Status: proposed | accepted | rejected | deprecated | superseded by ADR-NNNN
+- Date: YYYY-MM-DD
+- Deciders: <names / handles>
+
+## Context and Problem Statement
+
+<2–4 sentences. The problem and the constraints that force a choice.
+State the problem, not the answer. Quantify. Cite any driver (constitution
+section, spec/plan fork) that imposed this.>
+
+## Considered Options
+
+- <option 1>
+- <option 2>
+- <option 3>
+
+## Decision Outcome
+
+Chosen: **<option>**, because <the one-line justification tying back to
+the dominant driver>.
+
+## Consequences
+
+- Good: <what improves>
+- Bad: <what degrades / what you now own>
+- Follow-up: <concrete next work, linked to a tracker or future ADR>
+```
+
+## Full template (MADR 4.0.0, annotated)
+
+Add the optional sections — Decision Drivers, per-option Pros and Cons, Confirmation, More Information — when the decision is contested enough to need them.
+
+```markdown
+# NNNN. <short decision title>
+
+- Status: proposed
+- Date: YYYY-MM-DD
+- Deciders: <names>
+
+## Context and Problem Statement
+
+<The forces at play. Problem + constraints, quantified. End with the
+question being decided.>
+
+## Decision Drivers <!-- optional, but usually worth it -->
+
+- <driver 1, e.g. "EU data residency (constitution §data-residency)">
+- <driver 2, e.g. "team SQL fluency, no NoSQL ops experience">
+- <driver 3, e.g. "p99 < 100ms at 2k writes/min">
+
+## Considered Options
+
+- <option 1>
+- <option 2>
+- <option 3>
+
+## Decision Outcome
+
+Chosen: **<option>**, because <justification scored against the drivers>.
+
+### Confirmation <!-- optional -->
+
+<How we'll confirm the decision is implemented as intended — a review,
+a test, an architecture-fitness check.>
+
+## Pros and Cons of the Options <!-- optional -->
+
+### <option 1>
+
+- Good, because <…>
+- Bad, because <…>
+
+### <option 2>
+
+- Good, because <…>
+- Bad, because <…>
+
+## Consequences
+
+- Good: <upside bought>
+- Bad: <price paid / new ownership>
+- Risk: <what could go wrong>
+- Follow-up: <linked tasks>
+
+## More Information <!-- optional -->
+
+<Links, benchmarks, the meeting that spawned this, related ADRs.>
+```
+
+## Worked example — `0007-choose-postgres.md`
+
+```markdown
+# 7. Choose Postgres over DynamoDB for the primary store
+
+- Status: accepted
+- Date: 2026-06-02
+- Deciders: @alice, @bob
+
+## Context and Problem Statement
+
+The billing service needs a primary datastore. Data is strongly
+relational (invoices, line items, customers with foreign keys),
+write volume ~2k/min, the team is 3 engineers with deep SQL and no
+NoSQL operational experience, and EU data residency is mandatory
+(constitution §data-residency). Which store do we adopt?
+
+## Decision Drivers
+
+- Relational integrity: transactional, foreign-key-enforced invoicing
+- Team fluency: SQL high, NoSQL ops ~zero
+- EU residency + self-host option
+- Operational risk for a 3-person team
+
+## Considered Options
+
+- Postgres (managed, EU region)
+- DynamoDB
+- MongoDB Atlas
+
+## Decision Outcome
+
+Chosen: **Postgres (managed, EU region)**, because it natively matches
+the relational shape of the data and the team's existing fluency, at the
+lowest operational risk for a small team.
+
+## Pros and Cons of the Options
+
+### Postgres
+- Good, because native ACID transactions and foreign keys fit invoicing.
+- Good, because the whole team is productive day one.
+- Bad, because we own connection-pooling and vertical-scaling sooner.
+
+### DynamoDB
+- Good, because effectively infinite write scaling, hands-off ops.
+- Bad, because relational integrity is app-enforced — error-prone for billing.
+- Bad, because no team experience and no EU self-host path (AWS-coupled).
+
+### MongoDB Atlas
+- Good, because flexible schema and EU regions available.
+- Bad, because multi-document transactions are awkward for invoicing.
+- Bad, because partial team fluency, medium operational risk.
+
+## Consequences
+
+- Good: ACID guarantees for invoices; mature tooling; team productive immediately.
+- Bad: we own connection-pool tuning and will hit vertical-scaling limits earlier.
+- Risk: a single-writer bottleneck at much higher volume.
+- Follow-up: provision a read replica before launch — tracked in ADR-0009.
+```
+
+## Worked example — supersession pair
+
+A prior decision is reversed. **Never edit the old decision** — write a new ADR and flip the old status.
+
+Old ADR, status line changed (and *only* the status line):
+
+```markdown
+# 4. Adopt REST for the public API
+
+- Status: superseded by ADR-0012
+- Date: 2025-11-03
+- Deciders: @alice
+
+## Context and Problem Statement
+
+We needed a wire format for the public API in v1. (…original context,
+options, decision and consequences left fully intact…)
+```
+
+New ADR that supersedes it:
+
+```markdown
+# 12. Adopt tRPC for the internal API
+
+- Status: accepted
+- Date: 2026-06-30
+- Deciders: @alice, @carol
+- Supersedes: ADR-0004
+
+## Context and Problem Statement
+
+ADR-0004 chose REST when clients were external and untyped. Clients are
+now exclusively our own TypeScript apps; the manual request/response typing
+that REST forced is a recurring source of drift and bugs. Reconsider the
+internal API transport.
+
+## Considered Options
+
+- Keep REST (status quo, ADR-0004)
+- tRPC (end-to-end TypeScript types)
+- GraphQL
+
+## Decision Outcome
+
+Chosen: **tRPC**, because every client is TypeScript and end-to-end type
+inference removes the drift class entirely, with no schema-layer overhead.
+
+## Consequences
+
+- Good: compile-time-safe client/server contract; no codegen step.
+- Bad: couples clients to a TypeScript server; no longer language-agnostic.
+- Follow-up: deprecate REST routes over two releases; update ADR-0004 status.
+```
+
+Then back-link: ADR-0004 → `superseded by ADR-0012`, ADR-0012 → `Supersedes: ADR-0004`. Both are reachable from the index.