@damiangilgonzalez/harness 1.3.7

package/skills/sop-builder/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: sop-builder
+description: "Use when a repeated process lives in one person's head, breaks when they are away, gets re-explained to every new hire, or produces inconsistent results — and needs writing down once so anyone or any agent can run it the same way. Also for auditing and rewriting an SOP that is stale, ignored or missing its branches. NOT capturing a meeting's decisions and action items (that is `meeting-notes`), NOT running a one-time project plan with milestones (that is `project-ops`)."
+tags:
+  - sop
+  - process-documentation
+  - standard-operating-procedure
+  - runbook
+  - process
+  - business-ops
+recommends:
+  - meeting-notes
+  - project-ops
+  - compliance
+  - technical-writing
+  - automation-flows
+  - people-ops
+profiles: []
+origin: risco
+---
+
+# SOP builder
+
+You keep re-explaining the same process. Write it down once, correctly, so it
+runs without you. That is the whole job: take a workflow living in one person's
+head, a Slack thread, or a screen recording, and turn it into a **standard
+operating procedure** — a document another human or agent can follow to get the
+same result every time.
+
+An SOP is not a meeting note and not a project plan. Hold the line:
+
+- **What was decided + who does what by when** → [`meeting-notes`](../meeting-notes/SKILL.md). That records a moment; you record a *recurring task*.
+- **Milestones, status, a thing with an end date** → [`project-ops`](../project-ops/SKILL.md). A project finishes; an SOP repeats forever.
+- **External help-center docs / product manuals** → [`technical-writing`](../technical-writing/SKILL.md). That writes for a customer; you write for the person inside the org who runs the routine.
+- **Regulated GxP quality-system SOPs with formal approval + audit trail** → [`compliance`](../compliance/SKILL.md) owns the regulatory gating. You write the operational document; defer the sign-off framework to them.
+- **Turning the documented steps into a flow / webhook / script** → [`automation-flows`](../automation-flows/SKILL.md). You document; they automate.
+- **One specific new hire's first-week checklist + accounts** → [`people-ops`](../people-ops/SKILL.md). You write the *reusable* procedure they'll follow, not their personal tracker.
+
+The payoff is real but conditional: standardizing a process can cut errors by
+up to ~90% — **only when the SOP is clear and easy to follow**. A correct SOP
+nobody can read changes nothing. Usability is the whole game.
+
+## The capture-to-SOP loop
+
+This is the spine. Run it in order; do not skip the test step.
+
+1. **Pick one process.** One trigger in, one defined output out. If you can't
+   name the trigger and the output, you're scoping a department, not an SOP.
+2. **Capture the real flow** — interview the owner *or* read their recording/
+   transcript. Capture how it actually runs, not how it's supposed to.
+3. **Find the decisions and exceptions.** Where does it fork? Where does it
+   break when the owner is out? These are what a linear draft will miss.
+4. **Choose the format by flow shape** (next section). Linear ≠ branching ≠
+   parallel, and each wants a different shape.
+5. **Draft at the right altitude** — who does what and when, not every keystroke.
+6. **Test it on someone who has never done the task.** If they get stuck or ask
+   a question, the SOP has a gap — fix the document, not the person.
+7. **Assign an accountable owner and a review date.** Unowned, undated SOPs are
+   dead on arrival.
+
+Steps 3 and 6 are the ones teams skip and the reason most SOPs fail in the
+wild — a happy-path document breaks the moment reality forks.
+
+## Scope the right altitude
+
+An SOP and a work instruction are different documents. Per ISO 9001:2015 a
+procedure is "a specified way to carry out an activity." Don't bloat an SOP with
+keystroke detail — that's a separate work instruction, and one SOP links to
+several of them.
+
+| Altitude | Answers | Example line | Belongs in |
+| --- | --- | --- | --- |
+| SOP | *who* does *what* and *when* (the roadmap) | "The editor approves the draft before it's scheduled." | The SOP body |
+| Work instruction | *how* one operator does one task (the GPS) | "Click Settings → Schedule → pick 09:00, hit Confirm." | A linked WI, not inline |
+
+Rule of thumb: if removing a line wouldn't change *who* is accountable or *what*
+the next decision is, it's probably a keystroke — link it out or cut it. A
+reader who already knows the tool should not have to scroll past click-by-click
+detail to find the one decision that matters.
+
+## Pick the format by flow shape
+
+Match format to the shape of the work, not to preference. A mismatched format is
+a top adoption killer — people abandon an SOP that fights how the task actually
+moves.
+
+| Flow shape | Use | Why |
+| --- | --- | --- |
+| Strictly linear, every time the same | Numbered step-by-step | The order *is* the procedure; numbers carry it. |
+| Many parallel pieces, done by experienced people | Checklist | They know *how*; they need to not forget a piece, not be walked through it. |
+| Has decision points / forks / "it depends" | Flowchart or decision table | A numbered list hides branches inside prose and readers miss them. |
+
+If the process has even one real "if X then Y" fork, do **not** force it into a
+flat numbered list. The fork is exactly the part that breaks under pressure, and
+a flat list buries it.
+
+## The capture step
+
+Garbage in, garbage SOP. Capture how the work *actually* runs.
+
+**From a recording (the fast path).** A team hand-writing one SOP spends ~3–5
+hours; recording the task once (10–15 min) and extracting steps from the
+video/transcript is reported 10–20x faster. Treat the recording as the single
+source of truth, then prune to the SOP. Crucially: **do not invent steps the
+source never shows.** If the transcript skips a step, flag the gap — don't
+backfill it from imagination.
+
+**From an interview**, surface the hidden branches with probes the owner won't
+volunteer:
+
+- "Walk me through the last time you did this, start to finish."
+- "Where does this break when you're on holiday?" — the single best
+  branch-finder; it surfaces the tacit knowledge that lives only in their head.
+- "What's the most common thing that goes wrong, and what do you do then?"
+- "When do you have to ask someone else before continuing?" (→ an escalation).
+- "Is there a case where you skip a step or do it differently?" (→ a branch).
+
+People who actually do the work must be in the capture loop. An SOP written
+*about* people instead of *with* them is the classic reason it goes unfollowed.
+The full 10–12 question interview script is in
+[`references/sop-skeleton.md`](references/sop-skeleton.md).
+
+## The SOP skeleton
+
+Four sections are load-bearing and appear in essentially every credible
+template: **purpose, scope, responsibilities, procedure**. Everything else is
+supporting structure. Mark sections mandatory vs optional-by-size:
+
+| Section | Status | Note |
+| --- | --- | --- |
+| Title + ID/version | Mandatory | One process, one document. |
+| Purpose | Mandatory | Why this exists, in one sentence. |
+| Scope | Mandatory | What's in, what's out, when it triggers. |
+| Owner (the "A" in RACI) | Mandatory | Exactly one accountable person. |
+| Trigger | Mandatory | The event that starts the procedure. |
+| Steps | Mandatory | The numbered/checklist/branched body. |
+| Decision points | If it branches | The forks, written explicitly. |
+| Quality check | Mandatory | How you know the output is correct. |
+| Output | Mandatory | The defined thing produced. |
+| Exceptions / escalation | If it can fail | What to do when it goes wrong. |
+| RACI matrix | If >1 role | Only when the process spans roles. |
+| Change log | Mandatory | Version, date, author, one-line what-changed. |
+| Next-review date | Mandatory | See "Keep it alive". |
+
+A RACI clarifies ownership when more than one role touches the process:
+Responsible does it, Accountable owns the outcome (exactly one), Consulted gives
+input, Informed is kept in the loop. A solo task does **not** need a matrix —
+don't add ceremony the process doesn't carry. The full copy-paste template with
+per-field guidance lives in
+[`references/sop-skeleton.md`](references/sop-skeleton.md).
+
+## Write it so it's actually used
+
+SOPs go unfollowed because of the document, not the people: lack of clarity,
+cognitive overload from length and jargon, and staleness. Under pressure people
+default to memory over a wall of text. So write short, active, and concrete.
+
+- **One action per step.** Two verbs in a step means a reader can do half and
+  think they're done.
+- **Active voice, named actor.** Who does it must be unambiguous.
+- **No internal jargon** the next hire won't know — or define it once.
+
+Bad → Good:
+
+```markdown
+Bad:  The newsletter should be reviewed and then it gets scheduled, making
+      sure that everything is fine before it goes out.
+Good: 1. Editor reviews the draft against the checklist in §4.
+      2. Editor schedules the approved draft for 09:00 Tuesday.
+      3. Editor confirms the send shows in the queue.
+```
+
+The bad version hides three actions, names no actor, and uses passive voice that
+lets everyone assume someone else did the check.
+
+## Branches and exceptions — the section people skip
+
+Branching logic, exceptions/escalations, and the change log are the three
+sections SOPs most often omit, and the reason they fail in production. Write the
+fork explicitly; don't bury it in prose.
+
+```markdown
+Step 4 — Check the invoice total.
+  - If total ≤ €1,000 → approve and proceed to Step 5.
+  - If total > €1,000 → route to Finance lead for sign-off, then Step 5.
+  - If the PO number is missing → STOP. Escalate to <owner>; do not approve.
+```
+
+Every exception needs a named escalation target and a clear stop condition. "If
+unsure, ask someone" is not an escalation — name the role and the trigger. You
+don't need a sprawling flowchart for three forks; inline `if X then Y` lines are
+enough until the branch count makes a decision table or flowchart clearer (see
+"Pick the format").
+
+## Keep it alive
+
+An SOP without an owner and a review date is already dead. Every SOP carries:
+
+- **One accountable owner** — the person who answers for the outcome.
+- **A change log** — version, date, author, one line on what changed. Without
+  it, nobody trusts which version is current.
+- **A next-review date.** Reviews are annual minimum *plus* trigger-based: after
+  a process or tool change, after an incident, or after an audit.
+
+Treat an SOP unreviewed for **18+ months as unreliable** — it likely describes a
+process that no longer exists. When the review fires, re-run the capture loop on
+the diff, not the whole document.
+
+For **regulated** quality systems (GxP, formal approval workflows, audit-trail
+sign-off), write the operational content here and hand the approval/gating
+framework to [`compliance`](../compliance/SKILL.md). Once the SOP is stable and
+you want the steps executed automatically, hand it to
+[`automation-flows`](../automation-flows/SKILL.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+| --- | --- | --- |
+| Keystroke-level SOP ("click Settings, then…") | Bloats the doc; rots the day the UI changes | Keep SOP at who/what/when; link work instructions |
+| Flat numbered list for a branching process | Hides the forks that break under pressure | Use a decision table / flowchart for branches |
+| Happy-path only, no exceptions | Breaks the first time reality forks | Write `if X then Y` + a named escalation |
+| No owner, no review date | Goes stale silently, nobody trusts it | Name one accountable owner + a next-review date |
+| Written *about* the doer, not *with* them | Misses tacit steps; gets ignored | Interview/record the person who runs it |
+| Inventing steps the recording never showed | Ships a procedure that doesn't match reality | Flag gaps; capture the missing step, don't guess |
+| Wall of passive-voice prose | Cognitive overload; people fall back to memory | One action per step, active voice, named actor |
+| RACI on a solo task | Ceremony the process doesn't carry | Add a matrix only when >1 role touches it |
+
+## Reference
+
+Pull the full fill-in template, the 10–12 question capture interview script, the
+format-selection decision table, and a complete worked Bad→Good example SOP from
+[`references/sop-skeleton.md`](references/sop-skeleton.md). Keep this body lean;
+reach for the template when you're actually drafting.

package/skills/sop-builder/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — sop-builder
+
+These cases are run by the catalog's eval harness (or read by hand) to check two
+things. First, that the `description` triggers on real process-documentation asks
+— including the non-obvious bus-factor symptom and the Spanish phrasing — while
+routing meeting-decision, project-plan, help-doc, automation, and single-hire
+onboarding asks to the correct sibling (`meeting-notes`, `project-ops`,
+`technical-writing`, `automation-flows`, `people-ops`). Second, the `capability`
+case is a rubric checked by human or model judgment, not an automated assertion:
+feed the messy lead-triage transcript and confirm the produced SOP hits the right
+altitude, names an owner and review date, writes the two branches and the
+exception, uses active one-action-per-step phrasing, includes a change-log stub,
+and does not invent steps the source never showed. There is no `verify.sh` — the
+output is a written procedure, so rigor lives in this capability rubric.

package/skills/sop-builder/evals/cases.yaml

@@ -0,0 +1,48 @@
+skill: sop-builder
+
+should_trigger:
+  - prompt: "Can you help me write an SOP for how we publish the weekly newsletter?"
+    why: Direct ask for the core artifact — a standard operating procedure for a recurring task.
+  - prompt: "Every time Maria goes on holiday the refund process breaks because nobody else knows how she does it."
+    why: Non-obvious. The bus-factor symptom of a process living in one head, with no SOP keyword present.
+  - prompt: "I recorded a Loom of me doing the month-end close — turn it into a written procedure."
+    why: The recording-as-source capture path; recording-to-SOP is a named fast path.
+  - prompt: "Documenta este proceso paso a paso para que cualquiera del equipo lo pueda hacer."
+    why: Spanish trigger — document this process step by step so anyone on the team can run it.
+  - prompt: "Our team does the client handoff differently every time and the results are inconsistent — standardize it."
+    why: Standardization-from-inconsistency symptom, no SOP keyword; the core when-to-use.
+  - prompt: "This SOP is two years old, nobody follows it, and it has no exception handling — fix it."
+    why: The audit/rewrite path — a stale SOP past the 18-month staleness line, missing its branches.
+
+should_not_trigger:
+  - prompt: "Write up what we decided in today's standup and the action items."
+    route_to: meeting-notes
+    why: Recording a moment's decisions and actions, not documenting a repeatable procedure.
+  - prompt: "Build the project plan with milestones and owners for the Q3 launch."
+    route_to: project-ops
+    why: A one-time effort with an end date and milestones, not a recurring routine.
+  - prompt: "Write the help-center article explaining how customers reset their password."
+    route_to: technical-writing
+    why: External reader and product surface — a help doc, not an internal operating procedure.
+  - prompt: "Now automate this documented process with a webhook and a script."
+    route_to: automation-flows
+    why: Building the automation from steps, not capturing and writing the procedure.
+  - prompt: "Set up the new hire's first-week onboarding checklist and accounts."
+    route_to: people-ops
+    why: One specific employee's onboarding tracker, not the reusable procedure they follow.
+
+capability:
+  - scenario: >
+      Given a messy transcript of someone describing how they triage and respond to
+      inbound sales leads — containing two hidden decision points (lead size routing,
+      and a "spam/not-a-real-lead" filter) and one exception (CRM is down) — produce
+      a usable SOP.
+    must_include:
+      - Picks the SOP altitude (who/what/when), not a keystroke-level work instruction.
+      - Names exactly one accountable owner and sets a next-review date.
+      - Chooses a format that matches the branching flow (decision table or flowchart with inline if/then), not a flat numbered list.
+      - Surfaces and writes BOTH decision branches explicitly (lead-size routing and the spam filter).
+      - Writes the exception with a named escalation target and a stop/proceed condition (CRM down).
+      - Writes steps in active voice with one action each and a named actor.
+      - Includes a change-log / version stub.
+      - Does NOT invent steps absent from the source transcript; flags gaps instead of backfilling.

package/skills/sop-builder/references/sop-skeleton.md

@@ -0,0 +1,170 @@
+# SOP skeleton, interview script, and a worked example
+
+Lookup material for drafting. Copy the template, run the interview, pick the
+format, then prune to the leanest document that still survives the owner being
+out.
+
+## Format-selection decision table
+
+| Flow shape | Format | Tell |
+| --- | --- | --- |
+| Same steps, same order, every time | Numbered step-by-step | "First X, then Y, then Z" with no "it depends" |
+| Many independent pieces, skilled doer | Checklist | The doer knows *how*; the risk is forgetting a piece |
+| One or more decision points | Decision table or flowchart | The owner says "well, it depends on…" |
+| 1–3 small forks inside a mostly linear flow | Numbered steps + inline `if/then` | Don't reach for a flowchart yet |
+
+## The capture interview script
+
+Ask in roughly this order. The goal is to surface the branches and tacit steps
+the owner won't volunteer because, to them, they're obvious.
+
+1. In one sentence, what does this process produce, and what kicks it off?
+2. Walk me through the last real time you did it, start to finish — don't
+   clean it up.
+3. Where does this break when you're on holiday or out sick?
+4. What's the most common thing that goes wrong, and what do you do then?
+5. When do you have to check with or wait on someone else before continuing?
+6. Is there a case where you skip a step, or do it differently? When?
+7. What would a new hire get wrong on their first attempt?
+8. Which tool or system is the source of truth here?
+9. How do you know the output is *correct* before you call it done?
+10. What's the deadline or SLA, if any?
+11. Has anything about this changed recently that the old way got wrong?
+12. Who, besides you, needs to know when this is done?
+
+Map answers: Q3/Q4/Q5/Q6 → branches and escalations. Q9 → the quality check.
+Q5/Q12 → the RACI. Q2/Q7 → the step body.
+
+## The full SOP template
+
+```markdown
+# SOP-<id>: <process name>
+
+| Field          | Value                                  |
+| -------------- | -------------------------------------- |
+| Version        | 1.0                                    |
+| Owner (A)      | <named role/person — exactly one>      |
+| Last updated   | <YYYY-MM-DD> by <author>               |
+| Next review    | <YYYY-MM-DD>  (annual min + on change) |
+| Status         | Draft | Active | Retired                |
+
+## 1. Purpose
+One sentence: why this procedure exists.
+
+## 2. Scope
+- In scope: <what this covers>
+- Out of scope: <what it doesn't — hand-offs to other SOPs>
+- Trigger: <the event that starts it>
+
+## 3. Responsibilities (RACI — only if >1 role)
+| Activity | R | A | C | I |
+| -------- | - | - | - | - |
+| <step>   |   |   |   |   |
+
+## 4. Procedure
+1. <Actor> does <one action>.
+2. <Actor> does <one action>.
+   - If <condition> → <branch>.
+   - If <condition> → escalate to <role>; STOP until resolved.
+3. ...
+
+## 5. Quality check
+How the doer confirms the output is correct before calling it done.
+
+## 6. Output
+The defined artifact/result this produces.
+
+## 7. Exceptions & escalation
+- <failure case> → <named escalation target> → <stop or proceed condition>
+
+## 8. Change log
+| Version | Date       | Author | What changed                |
+| ------- | ---------- | ------ | --------------------------- |
+| 1.0     | YYYY-MM-DD | <name> | Initial version             |
+```
+
+Mandatory regardless of size: title/version, purpose, scope, owner, trigger,
+steps, quality check, output, change log, next-review date. Add §3 RACI only
+when more than one role touches the process; add §7 only when the process can
+fail in a way the doer must handle.
+
+## Worked example — "publish the weekly newsletter"
+
+### Bad (the wall-of-prose version that gets ignored)
+
+```markdown
+# Newsletter Process
+
+The newsletter goes out weekly. Someone writes it and then it should be
+reviewed and scheduled, making sure everything looks good and the links work
+before it's sent. If there are issues they should be fixed. Marketing owns it.
+```
+
+Problems: no trigger, no named actor (passive "should be reviewed"), no
+decision for what "issues" means, no quality check you can verify, no owner you
+can call, no version or review date, no escalation. A new hire learns nothing
+runnable from this.
+
+### Good (right altitude, branches explicit, alive)
+
+```markdown
+# SOP-014: Publish the weekly newsletter
+
+| Field        | Value                               |
+| ------------ | ----------------------------------- |
+| Version      | 2.1                                 |
+| Owner (A)    | Content Lead                        |
+| Last updated | 2026-05-20 by J. Roca               |
+| Next review  | 2027-05-20 (or on tool change)      |
+| Status       | Active                              |
+
+## 1. Purpose
+Ship one reviewed newsletter every Tuesday 09:00 without the Content Lead
+present.
+
+## 2. Scope
+- In: drafting through send for the weekly list.
+- Out: campaign design (see SOP-008), list hygiene (see SOP-021).
+- Trigger: Monday 10:00, draft due in the CMS.
+
+## 3. Responsibilities
+| Activity     | R       | A            | C        | I    |
+| ------------ | ------- | ------------ | -------- | ---- |
+| Draft        | Writer  | Content Lead | —        | —    |
+| Review       | Editor  | Content Lead | —        | —    |
+| Schedule     | Editor  | Content Lead | —        | Team |
+
+## 4. Procedure
+1. Writer completes the draft in the CMS by Monday 10:00.
+2. Editor reviews the draft against the §5 checklist.
+   - If a link is broken or a claim is unsourced → return to Writer; STOP
+     until fixed.
+   - If the send list is > 50k recipients → notify Finance before scheduling
+     (billing tier).
+3. Editor schedules the approved draft for Tuesday 09:00.
+4. Editor confirms the send appears in the queue and pings #marketing.
+
+## 5. Quality check
+All links resolve (200), subject line ≤ 60 chars, one CTA, preview rendered
+on mobile.
+
+## 6. Output
+One scheduled newsletter visible in the send queue for Tuesday 09:00.
+
+## 7. Exceptions & escalation
+- CMS down at scheduling time → escalate to Content Lead; hold, do not send
+  late without sign-off.
+- Legal/PR-sensitive content → route to Comms before send.
+
+## 8. Change log
+| Version | Date       | Author  | What changed                       |
+| ------- | ---------- | ------- | ---------------------------------- |
+| 2.1     | 2026-05-20 | J. Roca | Added >50k list Finance notice     |
+| 2.0     | 2026-02-11 | J. Roca | Split list-hygiene into SOP-021    |
+```
+
+Note what changed: a named actor on every step, two explicit branches plus an
+escalation, a verifiable quality check, one accountable owner, and a live change
+log. It stays at SOP altitude — "schedules the approved draft," not "click
+Settings → Schedule → 09:00." Those keystrokes, if the team needs them, go in a
+linked work instruction, not here.

package/skills/source-grounded-development/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: source-grounded-development
+description: "Use when implementation or review depends on current version-specific framework, SDK, protocol or platform behaviour and memory is unsafe. Detects exact local versions, verifies primary sources, tests applicability and marks unknowns. NOT a standalone cited memo (`research-ops`), NOT diagnosis of a reproduced failure (`superpowers:systematic-debugging`)."
+tags: [official-docs, primary-sources, version-detection, implementation, verification]
+recommends: [research-ops, write-adr, technical-writing]
+profiles: [core, ui, full]
+origin: risco
+---
+
+# source-grounded-development — make current facts part of the change
+
+Use this when correctness depends on what a framework, SDK, API, standard or hosted platform **does now for the exact version in this repository**. The deliverable is still code, a review or an implementation decision; sources are the evidence behind it, not a separate essay.
+
+This is narrower than `../research-ops/SKILL.md`: research-ops answers an open question with a cited memo. Here, the question exists because a concrete change cannot safely proceed from memory.
+
+## The loop
+
+```text
+DETECT → QUESTION → SOURCE → APPLY → PROVE → REPORT
+```
+
+### 1. DETECT the actual version and environment
+
+Read the repository before the web:
+
+- lockfiles and manifests, not only a README;
+- runtime and compiler configuration;
+- generated client/server versions;
+- deployment target and enabled compatibility flags;
+- existing wrapper code that may override documented defaults.
+
+Record an evidence line such as: `Next 16.2.1 from pnpm-lock.yaml; Node 24 from .nvmrc; App Router; deployed to Vercel.` If versions conflict, stop treating the docs as applicable until the conflict is resolved.
+
+### 2. QUESTION only the claims that can change the implementation
+
+Build a small claim ledger. Each row is one decision-sensitive statement:
+
+```text
+claim | exact component/version | evidence needed | source | applicability | status
+```
+
+Examples: whether a callback is invoked on retry, the default cookie policy, an API’s idempotency semantics, a deprecated option’s replacement, or a browser feature’s support boundary. Do not cite obvious local code or generic programming facts just to make the list longer.
+
+### 3. SOURCE by authority and freshness
+
+Prefer, in order:
+
+1. the repository and installed type definitions for local truth;
+2. official versioned documentation and migration/release notes;
+3. specifications, RFCs or provider API references;
+4. upstream source or tests when documentation is ambiguous;
+5. reputable secondary material only as a lead, never as the final authority for a disputed behaviour.
+
+Use the current page that matches the detected version. A search snippet, an undated blog, a forum answer or remembered API shape is not proof. When two primary sources disagree, show the disagreement and test the behaviour; do not average them into false certainty.
+
+### 4. APPLY the source to this repository
+
+For every useful source, state why it applies here:
+
+- same major/minor version or a documented compatibility range;
+- same runtime, router, transport, deployment mode or feature flag;
+- no local wrapper/configuration that changes the default;
+- publication or update date appropriate to a fast-moving claim.
+
+Then make the smallest implementation decision that the evidence supports. Do not turn examples from docs into architecture by cargo cult. Examples demonstrate an API; the repository still determines ownership, boundaries and error policy.
+
+### 5. PROVE behaviour locally
+
+Documentation tells you intended behaviour. A local test proves the integration:
+
+- add or run a focused contract/regression test;
+- compile against installed types;
+- exercise a minimal reproduction when defaults or runtime order matter;
+- run the stack’s normal verification gate after the focused proof.
+
+If local evidence contradicts the source, preserve the reproduction and investigate version/config drift. Do not silently choose whichever result is more convenient.
+
+### 6. REPORT without polluting the code
+
+End with:
+
+- versions and environment detected;
+- material claims verified and their primary links;
+- implementation choices those claims changed;
+- local evidence run;
+- assumptions still **UNVERIFIED**, with the consequence if wrong.
+
+Put source links in the final report, PR description or a durable decision record when the rationale must outlive the task. Do not scatter documentation URLs through source comments unless the code’s invariant genuinely cannot be understood without that external contract.
+
+## Stop conditions
+
+Stop searching when every decision-sensitive claim is verified, contradicted or explicitly marked unverified and the local proof is green. Search breadth is not quality. A fifth article repeating the official reference adds no evidence.
+
+Do not use this skill as a reason to delay reversible work indefinitely. If a primary source is unavailable, name the uncertainty, choose the safest reversible option, add a proof/guard, and state what would trigger revisiting it.
+
+## Anti-patterns
+
+| Smell | Correction |
+|---|---|
+| A reproduced bug is replaced by a docs tour | `superpowers:systematic-debugging` owns diagnosis; use this only for the disputed versioned claim. |
+| A broad open question is forced into implementation | Route the cited memo to `research-ops`. |
+| A lasting architecture choice disappears into a task summary | Preserve it in `write-adr` with this ledger as evidence. |
+| A search result or secondary article is presented as official | Follow it to the primary source or mark the claim unverified. |
+| “Latest docs” are read before the lockfile | Detect the local version and mode first; then choose applicable docs. |
+
+## Orientación (siempre)
+
+Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `docs/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el “¿instalo la skill que falta?”.)

package/skills/source-grounded-development/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — source-grounded-development
+
+The routing cases separate version-sensitive implementation evidence from general research, debugging, ADRs, docs and security review. The capability rubric requires the full local-version → primary-source → applicability → local-proof chain and treats unverified deployment assumptions as visible risk.

package/skills/source-grounded-development/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: source-grounded-development
+
+should_trigger:
+  - prompt: "Before changing sessions, verify the installed Express and express-session versions against their official production guidance."
+    why: "A concrete implementation depends on current version-specific framework behaviour."
+  - prompt: "No te fíes de memoria: mira el lockfile y la documentación oficial de Stripe para comprobar la semántica de reintentos."
+    why: "Spanish request for local version detection and primary-source verification."
+  - prompt: "This SDK changed between majors; prove which callback contract applies to the version in this repo."
+    why: "A version boundary changes implementation correctness."
+  - prompt: "Comprova amb fonts primàries si aquesta opció està deprecada en la versió instal·lada i quin reemplaçament toca."
+    why: "Catalan request for official deprecation evidence tied to the installed version."
+  - prompt: "Implement the browser API only after checking its current specification and support boundary, then test the fallback."
+    why: "Protocol/browser behaviour requires primary evidence plus local proof."
+  - prompt: "Review this integration and cite the official pages behind every provider-specific claim that affects the verdict."
+    why: "A review depends on current provider contracts rather than recalled assumptions."
+
+should_not_trigger:
+  - prompt: "Research whether passkeys improve consumer login conversion and deliver a cited memo."
+    route_to: research-ops
+    why: "The artifact is a standalone research memo, not an implementation grounded in an installed version."
+  - prompt: "The checkout test fails on every third retry; reproduce it and find the root cause."
+    route_to: external:superpowers-systematic-debugging
+    why: "A concrete failure needs diagnosis via superpowers' systematic-debugging; documentation may support but does not own the workflow."
+  - prompt: "Record why we selected Kafka over SQS and preserve the rejected alternatives."
+    route_to: write-adr
+    why: "Durable decision rationale is write-adr's job."
+  - prompt: "Write the public setup guide for our SDK users."
+    route_to: technical-writing
+    why: "The deliverable is documentation, not source-grounded implementation."
+  - prompt: "Audit this webhook handler for SSRF and secret leakage."
+    route_to: secure-coding
+    why: "Security threat/control review owns the task."
+
+capability:
+  - scenario: "Implement production session cookies for an application whose framework and session-library versions are pinned but whose deployment proxy behaviour is unclear."
+    must_include:
+      - "Reads lockfiles, runtime configuration, deployment target, and local wrappers before choosing documentation."
+      - "Creates a bounded claim ledger covering cookie defaults, proxy trust, secure transport, secret handling, and session-store production requirements."
+      - "Uses version-matching official docs, release/migration notes, specifications, or upstream source; secondary sources are not treated as final authority."
+      - "Explains why each material source applies to this runtime and flags deployment facts that remain unverified."
+      - "Adds or runs focused local proof plus the repository's normal verification gate instead of trusting documentation alone."
+      - "Reports citations in the result or decision record without filling ordinary source comments with URLs."