rsc-universal 0.1.1

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're out, gets re-explained to every new hire, or produces inconsistent results because everyone does it differently — and needs to be written down once so anyone (or an agent) can run it the same way. Also when an existing SOP is stale, ignored, or missing its branches and needs an audit + rewrite. Triggers: 'write an SOP for how we publish the weekly newsletter', 'document this process step by step', 'turn this Loom/recording into a written procedure', 'it breaks every time Maria is on holiday because nobody else knows how she does it', 'our client handoff is different every time, standardize it', 'documenta este proceso paso a paso', 'crea un procedimiento para que cualquiera lo pueda hacer'. 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.