skilldrop-cli 0.11.6 → 0.11.7

package/README.md

@@ -24,60 +24,190 @@ skilldrop ships **loops**, not just parts. A loop is a named sequence of stages
 
 A loop *sequences* skills — it never contains one. Every skill stays independently installable and runnable on its own, which is what keeps a single-folder copy working in Cursor, Kiro, or Aider.
 
-| Loop | Takes | Gate | Produces |
+Four loops cover the lifecycle, and they are separated by **reversibility** — how expensive the mistake is to unwind — which is why each gets its own gate rather than folding into a neighbour:
+
+| Loop | Takes | Gate | Produces | Mistake costs |
+|---|---|---|---|---|
+| [`discover`](loops/discover/LOOP.md) | interviews, journeys, a strategy question | **G0** human — a person ratifies the brief | a ratified requirement | a re-brief |
+| [`design`](loops/design/LOOP.md) | a ratified requirement | **G1** review — `council-review`'s panel | a recorded decision (ADR) | months, unwound in code |
+| [`build`](loops/build/LOOP.md) | an agreed requirement or triaged defect | **G2** mechanical — `pre-merge-review`'s gate script decides | merged code | a revert |
+| [`operate`](loops/operate/LOOP.md) | a shipped service | **G3** human — the incident is closed | a postmortem and runbook deltas | live users, irreversible |
+
+Plus one **wrapper**, which is not a lifecycle stage but the two passes either side of *any* generator:
+
+| Wrapper | Takes | Gate | Produces |
 |---|---|---|---|
-| [`build`](loops/build/LOOP.md) | an agreed requirement or triaged defect | **G2** mechanical — `pre-merge-review`'s gate script decides | merged code |
 | [`ship-a-draft`](loops/ship-a-draft/LOOP.md) | raw notes, a transcript, a ticket | **G4** review — `doc-critique`'s verdict | a stakeholder-ready artifact |
 
 Every gate emits a verdict from one shared vocabulary ([`contracts/terminals.json`](contracts/terminals.json)) in five classes — pass, conditional, revise, redirect, blocked — so `READY`, `PROCEED` and `SHIP IT` are recognisably the same kind of answer. Both diagrams render on GitHub; the Mermaid sources live in [`docs/`](docs/) for easy re-rendering.
 
-### `ship-a-draft` — the knowledge-work loop
+*Diagrams below are generated from each loop's `loop.json` by [`build_loops.py`](build_loops.py) — edit the contract, not the picture.*
+
+### `discover` — raw signal to a ratified requirement
 
-Raw input becomes a stakeholder-ready artifact — and loops back through review until it's approved.
+Interviews, journeys and strategy questions become one tagged brief, then numbered requirements a **human ratifies** before any design starts.
+
+<!-- loop:discover:start -->
 
 ```mermaid
 %%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
 flowchart LR
-    classDef input  fill:#FFF4E0,stroke:#E8A93B,stroke-width:2px,color:#7A4E00,font-weight:bold;
     classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
     classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
+    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
     classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
 
-    IN(["Raw input<br/>notes · ticket · transcript"]):::input
-    brief["Structure the brief"]:::gen
-    gens["Draft the artifact"]:::gen
-    crit["Review and refine"]:::review
-    ART(["Stakeholder-ready<br/>artifact"]):::ship
+    gather["gather<br/><small>requirements-interview +2</small>"]:::gen
+    structure["structure<br/><small>brief-intake</small>"]:::gen
+    specify["specify<br/><small>prd-draft</small>"]:::gen
+    ratify["ratify<br/><small>doc-critique</small>"]:::gate
+    G0{"G0 · human"}:::gate
+    DONE(["complete"]):::ship
+
+    gather --> structure
+    structure --> specify
+    specify --> ratify
+    ratify --> G0
+    G0 == "PROCEED" ==> DONE
 
-    IN --> brief --> gens --> crit
-    crit -- "revise" --> brief
-    crit == "approved" ==> ART
+    G0 -- "REVISE (max 3)" --> structure
 ```
 
-### `build` — code: implement and verify
+<!-- loop:discover:end -->
 
-A feature spec becomes shippable code through a self-correcting loop — generate, adversarially challenge, close the gaps, re-check — until the review is clean or a 3-round cap is hit. This is the [`feature-implement-loop`](skills/feature-implement-loop/SKILL.md) skill.
+### `design` — a requirement to a recorded decision
+
+Constraints first, then structure and diagrams, then an attack, then a panel that must agree — and only then is the decision written down as an ADR.
+
+<!-- loop:design:start -->
 
 ```mermaid
 %%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
 flowchart LR
-    classDef input  fill:#FFF4E0,stroke:#E8A93B,stroke-width:2px,color:#7A4E00,font-weight:bold;
     classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
     classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
     classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
     classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
 
-    IN(["Feature / story<br/>description + acceptance criteria"]):::input
-    gC["Write and update<br/>code and tests"]:::gen
-    revC["Challenge the code"]:::review
-    gate{"Gaps found?"}:::gate
-    SHIP(["Feature ready<br/>to be shipped"]):::ship
+    constrain["constrain<br/><small>nfr-spec</small>"]:::gen
+    shape["shape<br/><small>design-doc·architecture-diagrams</small>"]:::gen
+    threat["threat<br/><small>threat-model</small>"]:::review
+    ratify["ratify<br/><small>council-review</small>"]:::gate
+    record["record<br/><small>adr-generator</small>"]:::gen
+    G1{"G1 · review"}:::gate
+    DONE(["complete"]):::ship
+
+    constrain --> shape
+    shape --> threat
+    threat --> ratify
+    ratify --> G1
+    G1 == "PROCEED" ==> record
+    record --> DONE
+
+    G1 -- "REVISE (max 3)" --> shape
+```
+
+<!-- loop:design:end -->
+
+### `build` — a requirement to merged code
+
+A vertical slice becomes shippable code through a self-correcting loop, gated by a script whose exit code decides. The inner generate-challenge cycle is the [`feature-implement-loop`](skills/feature-implement-loop/SKILL.md) skill.
+
+<!-- loop:build:start -->
 
-    IN --> gC --> revC --> gate
-    gate -- "yes (up to 3 rounds)" --> gC
-    gate == "no" ==> SHIP
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
+flowchart LR
+    classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
+    classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
+    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
+    classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
+
+    shape["shape<br/><small>user-story-splitter·bug-triage</small>"]:::gen
+    implement["implement<br/><small>feature-implement-loop</small>"]:::gen
+    verify["verify<br/><small>pre-merge-review</small>"]:::review
+    decide["decide<br/><small>council-review</small>"]:::gate
+    G2{"G2 · mechanical"}:::gate
+    G2_1{"G2.1 · human"}:::gate
+    DONE(["complete"]):::ship
+
+    shape --> implement
+    implement --> verify
+    verify --> G2
+    G2 == "READY" ==> decide
+    decide --> G2_1
+    G2_1 == "PROCEED" ==> DONE
+
+    G2 -- "NOT READY (max 3)" --> implement
+    G2_1 -- "REVISE (max 3)" --> shape
 ```
 
+<!-- loop:build:end -->
+
+### `operate` — a shipped service through detection and learning
+
+Instrument, write the runbook, communicate the incident, then feed the postmortem's runbook deltas straight back into the runbook. The one loop whose failures are live.
+
+<!-- loop:operate:start -->
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
+flowchart LR
+    classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
+    classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
+    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
+    classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
+
+    instrument["instrument<br/><small>observability-plan</small>"]:::gen
+    document["document<br/><small>runbook-generator</small>"]:::gen
+    respond["respond<br/><small>incident-comms</small>"]:::gen
+    learn["learn<br/><small>postmortem-generator</small>"]:::review
+    G3{"G3 · human"}:::gate
+    DONE(["complete"]):::ship
+
+    instrument --> document
+    document --> respond
+    respond --> learn
+    learn --> G3
+    G3 == "PROCEED" ==> DONE
+
+    G3 -- "REVISE (max 3)" --> document
+```
+
+<!-- loop:operate:end -->
+
+### `ship-a-draft` — raw input to a stakeholder-ready artifact
+
+The wrapper: structured intake before any generator, critique and a machine-residue scrub after. Loops back through intake — not the draft — until it's approved.
+
+<!-- loop:ship-a-draft:start -->
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
+flowchart LR
+    classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
+    classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
+    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
+    classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
+
+    intake["intake<br/><small>brief-intake</small>"]:::gen
+    draft["draft<br/><small>*</small>"]:::gen
+    critique["critique<br/><small>doc-critique</small>"]:::review
+    polish["polish<br/><small>output-hygiene</small>"]:::review
+    G4{"G4 · review"}:::gate
+    DONE(["complete"]):::ship
+
+    intake --> draft
+    draft --> critique
+    critique --> G4
+    G4 == "SHIP IT" ==> polish
+    polish --> DONE
+
+    G4 -- "MAJOR REWRITE (max 3)" --> intake
+```
+
+<!-- loop:ship-a-draft:end -->
+
 ## Skills in this repo
 
 ### Pipeline glue

package/loops/design/LOOP.md

@@ -0,0 +1,68 @@
+---
+name: design
+description: Take a ratified requirement to a recorded architectural decision — constraints, structure, diagrams, threats, then a panel that must agree before the decision is written down. Use when the user is designing a system, choosing an architecture, or asking how something should be built.
+---
+
+# design
+
+The loop with the worst reversibility profile in the repo. A discovery mistake costs a
+re-brief; a design mistake surfaces months later, in code nobody wants to unwind. That is why
+its gate is a **panel** — independent positions, surfaced cruxes, recorded dissent — and not
+a script, and why the decision is recorded only *after* the panel agrees.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `constrain` | generate | [`nfr-spec`](../../skills/nfr-spec/SKILL.md) | — |
+| 2 | `shape` | generate | [`design-doc`](../../skills/design-doc/SKILL.md), [`architecture-diagrams`](../../skills/architecture-diagrams/SKILL.md) | — |
+| 3 | `threat` | verify | [`threat-model`](../../skills/threat-model/SKILL.md) | — |
+| 4 | `ratify` | gate | [`council-review`](../../skills/council-review/SKILL.md) | **G1** review |
+| 5 | `record` | generate | [`adr-generator`](../../skills/adr-generator/SKILL.md) | — |
+
+## How to run this loop
+
+1. **Constrain before shaping.** `nfr-spec` first, always. A design produced before its
+   quality targets exist gets judged on taste, and taste does not survive a review panel.
+2. **Shape prose and picture together.** `design-doc` and `architecture-diagrams` are one
+   artifact in two renderings. A diagram that disagrees with the doc is a defect in both.
+3. **Attack it before ratifying.** `threat-model` consumes the design directly. Running it
+   after G1 means the panel ratified something nobody had attacked.
+4. **Ratify at G1.** `council-review` seats the standing panel, takes positions *before*
+   cross-talk, names the cruxes, and records dissent with "what would change our mind".
+   `REVISE` returns to `shape`. `SPLIT` and `RECONSIDER` leave the loop.
+5. **Record last.** `adr-generator` writes the decision *after* it is a decision, with the
+   rejected options and the reasoning that killed them. An ADR written before G1 is a proposal
+   wearing an ADR's clothes.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../contracts/terminals.json). `PROCEED WITH
+CONDITIONS` is the common outcome and the most abused: the conditions are part of the
+decision, and `record` must carry them into the ADR.
+
+## Non-interactive runs
+
+`council-review` can be run by an agent seating the panel itself, so G1 is satisfiable without
+a human. `SPLIT` is not — a genuine unresolved split needs a person. Emit
+`BLOCKED: need a decision-maker for <the crux>` and name the positions.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version, and record
+the stage as degraded. If `council-review` is missing, do not skip G1 — run the panel inline
+from the design's own quality attributes and say the seating was improvised.
+
+## Quality bar
+
+- **Quality targets exist before structure does.** `nfr-spec` is stage 1 because a design without numbers can only be argued about.
+- **The ADR names what was rejected and why.** A decision record with one option is a description of what happened, not a decision.
+- **Dissent is recorded, not resolved away.** A panel that always reaches consensus is not seating real positions.
+- **The diagram and the doc say the same thing.** They are checked against each other before G1, not after someone builds from the wrong one.
+
+## Anti-patterns to avoid
+
+- ❌ **Writing the ADR before G1.** It pre-commits the panel to a decision it has not made, and every reviewer can feel it.
+- ❌ **Running `threat-model` after ratification.** The panel then ratified an unattacked design, which is the failure this ordering exists to prevent.
+- ❌ **Treating `PROCEED WITH CONDITIONS` as `PROCEED`.** The conditions must reach the ADR; dropping them is how a conditional approval silently becomes unconditional.
+- ❌ **Skipping `constrain` because the NFRs are "obvious".** Obvious targets are the ones nobody writes down and everybody remembers differently.

package/loops/design/loop.json

@@ -0,0 +1,47 @@
+{
+  "$comment": "RFC-0028. The loop with the worst reversibility profile: a design mistake surfaces months later in code nobody wants to unwind. That is why its gate is a panel, not a script.",
+  "name": "design",
+  "version": "0.1.0",
+  "description": "Take a ratified requirement to a recorded architectural decision — constraints, structure, diagrams, threats, then a panel that must agree before the decision is written down. Use when the user is designing a system, choosing an architecture, or asking how something should be built.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "constrain",
+      "type": "generate",
+      "intent": "Name the quality targets before the structure, so the design is judged against numbers rather than taste.",
+      "skills": ["nfr-spec"]
+    },
+    {
+      "id": "shape",
+      "type": "generate",
+      "intent": "Write the design and render it. The prose and the picture are one artifact and must not disagree.",
+      "skills": ["design-doc", "architecture-diagrams"]
+    },
+    {
+      "id": "threat",
+      "type": "verify",
+      "intent": "Attack the design that now exists, before it is ratified rather than after it is built.",
+      "skills": ["threat-model"]
+    },
+    {
+      "id": "ratify",
+      "type": "gate",
+      "intent": "A standing panel takes independent positions before cross-talk, surfaces the cruxes, and records dissent.",
+      "skills": ["council-review"],
+      "gate": {
+        "id": "G1",
+        "kind": "review",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "RECONSIDER", "SPLIT", "BLOCKED"],
+        "revise_to": "shape"
+      }
+    },
+    {
+      "id": "record",
+      "type": "generate",
+      "intent": "Write the decision down with its rejected alternatives, so the next team inherits the reasoning and not just the outcome.",
+      "skills": ["adr-generator"]
+    }
+  ]
+}

package/loops/discover/LOOP.md

@@ -0,0 +1,66 @@
+---
+name: discover
+description: Take raw signal — interviews, journeys, a strategy question — to a requirement a human has ratified, so design starts from an agreed problem rather than an assumed one. Use when the user is deciding what to build, scoping a feature, or turning stakeholder conversations into requirements.
+---
+
+# discover
+
+The first loop of the lifecycle, and the cheapest one to run twice. Everything downstream
+inherits whatever this loop got wrong, which is why it ends at a **human** gate rather than a
+script: no check can tell you that you solved the wrong problem well.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `gather` | generate | [`requirements-interview`](../../skills/requirements-interview/SKILL.md), [`user-journey-map`](../../skills/user-journey-map/SKILL.md), [`strategy-analysis`](../../skills/strategy-analysis/SKILL.md) | — |
+| 2 | `structure` | generate | [`brief-intake`](../../skills/brief-intake/SKILL.md) | — |
+| 3 | `specify` | generate | [`prd-draft`](../../skills/prd-draft/SKILL.md) | — |
+| 4 | `ratify` | gate | [`doc-critique`](../../skills/doc-critique/SKILL.md) | **G0** human |
+
+## How to run this loop
+
+1. **Gather from whichever direction the signal arrives.** A stakeholder conversation →
+   `requirements-interview`. An existing experience with known friction → `user-journey-map`.
+   An open strategic question → `strategy-analysis`. Run one; running all three on the same
+   input produces three views of the same thing and no more information.
+2. **Structure once.** `brief-intake` tags every field `[explicit]` / `[implied]` /
+   `[inferred]` / `[missing]` with verbatim quotes. The tags are the deliverable — an
+   untagged brief hides which parts are somebody's assumption.
+3. **Resolve the missing before specifying.** `brief-intake` ends with what the downstream
+   skill will refuse to start without. Answer those; do not let `prd-draft` invent them.
+4. **Specify.** `prd-draft` turns the brief into numbered requirements a design can be held to.
+5. **Ratify at G0.** Run `doc-critique` against the PRD, then put the decision to a human.
+   The critique informs; the human decides. `REVISE` returns to `structure`, not to `specify`
+   — a weak PRD almost always means a thin brief.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../contracts/terminals.json). G0 emits `PROCEED`,
+`PROCEED WITH CONDITIONS`, `REVISE`, `RECONSIDER`, or `BLOCKED`. `RECONSIDER` leaves the loop:
+the problem itself is wrong, and no amount of re-briefing fixes that.
+
+## Non-interactive runs
+
+With no human present, G0 cannot be satisfied. Emit `BLOCKED: need ratification of <the
+brief's central claim>` and stop. Do not self-ratify — a fabricated goal corrupts every
+artifact the other four loops produce.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version of that
+stage, and record that it ran degraded. Never skip G0.
+
+## Quality bar
+
+- **Every field carries a provenance tag.** A brief that does not distinguish quoted from inferred cannot be ratified, only believed.
+- **`[missing]` is resolved or stated, never filled.** Inventing the goal, the customer, or the success measure is the one failure this loop exists to prevent.
+- **The requirements are numbered and testable.** "Fast" is not a requirement; a latency target is.
+- **A human ratifies before design starts.** G0 is the loop's only reason to exist — an unratified brief is a draft, whatever the critique said.
+
+## Anti-patterns to avoid
+
+- ❌ **Running all three `gather` skills to be thorough.** Three lenses on one input is not three inputs; pick the one that matches where the signal came from.
+- ❌ **Letting `prd-draft` fill a `[missing]` field.** That converts an open question into a fact nobody agreed to.
+- ❌ **Treating `doc-critique`'s `SHIP IT` as ratification.** The critique judges the document; G0 judges the problem.
+- ❌ **Returning `REVISE` to `specify`.** Re-writing the PRD from the same thin brief reproduces the same gaps in better prose.

package/loops/discover/loop.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "RFC-0028. The first loop of the lifecycle: nothing is designed or built until a human has ratified what problem is being solved. Cheapest loop to redo and the most expensive to skip.",
+  "name": "discover",
+  "version": "0.1.0",
+  "description": "Take raw signal — interviews, journeys, a strategy question — to a requirement a human has ratified, so design starts from an agreed problem rather than an assumed one. Use when the user is deciding what to build, scoping a feature, or turning stakeholder conversations into requirements.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "gather",
+      "type": "generate",
+      "intent": "Collect the raw signal from whichever direction it arrives: a stakeholder conversation, an existing user journey, or a strategic question.",
+      "skills": ["requirements-interview", "user-journey-map", "strategy-analysis"]
+    },
+    {
+      "id": "structure",
+      "type": "generate",
+      "intent": "Turn the mess into one brief with every field tagged explicit / implied / inferred / missing, so downstream can see what was assumed.",
+      "skills": ["brief-intake"]
+    },
+    {
+      "id": "specify",
+      "type": "generate",
+      "intent": "Turn the ratified brief into numbered requirements a design can be held to.",
+      "skills": ["prd-draft"]
+    },
+    {
+      "id": "ratify",
+      "type": "gate",
+      "intent": "A human agrees this is the problem worth solving. The critique informs that decision; it does not make it.",
+      "skills": ["doc-critique"],
+      "gate": {
+        "id": "G0",
+        "kind": "human",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "RECONSIDER", "BLOCKED"],
+        "revise_to": "structure"
+      }
+    }
+  ]
+}

package/loops/operate/LOOP.md

@@ -0,0 +1,69 @@
+---
+name: operate
+description: Take a shipped service through detection, response, and learning — instrument it, write the runbook, communicate the incident, then feed the postmortem's deltas back into the runbook. Use when the user is preparing to run a service, is in an incident, or is writing a postmortem.
+---
+
+# operate
+
+The only loop whose failures are **irreversible and live**. The other four can be re-run at
+the cost of time; this one runs while real users are affected. Its feedback edge is the point:
+`postmortem-generator` emits runbook deltas phrased as edits, and those go straight back into
+`document`. An incident that changes no procedure has not been learned from.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `instrument` | generate | [`observability-plan`](../../skills/observability-plan/SKILL.md) | — |
+| 2 | `document` | generate | [`runbook-generator`](../../skills/runbook-generator/SKILL.md) | — |
+| 3 | `respond` | generate | [`incident-comms`](../../skills/incident-comms/SKILL.md) | — |
+| 4 | `learn` | verify | [`postmortem-generator`](../../skills/postmortem-generator/SKILL.md) | **G3** human |
+
+## How to run this loop
+
+1. **Instrument first.** `observability-plan` decides what is measured and what pages a human.
+   You cannot respond to what you never detected, and you cannot write a runbook entry for an
+   alert that does not exist.
+2. **Write the runbook per alert.** Each alert the previous stage defined maps to a
+   `runbook-generator` entry. An alert with no procedure wakes someone who then has to think.
+3. **Respond to the audience the incident actually has.** `incident-comms` is staged —
+   detect, mitigate, resolve — and the stage determines the message. Writing a resolution
+   update during mitigation is the most common error here.
+4. **Learn at G3.** `postmortem-generator` analyses blamelessly and ends with runbook deltas.
+   A human signs off that the incident is closed. `REVISE` returns to `document`: the deltas
+   are the loop's output, and applying them is what closes it.
+
+Entering mid-loop is normal and expected. An incident starts at `respond`; a new service
+starts at `instrument`. Do not replay earlier stages for their own sake.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../contracts/terminals.json). G3 emits `PROCEED`,
+`PROCEED WITH CONDITIONS`, `REVISE`, or `BLOCKED`. `PROCEED WITH CONDITIONS` means the
+incident is closed but named follow-ups are outstanding — they travel with the postmortem.
+
+## Non-interactive runs
+
+Never fabricate incident facts — timings, impact, customer counts, root cause. When the
+timeline is incomplete, emit `BLOCKED: need <the missing facts>` and name them. A confident
+postmortem built on guessed impact is worse than no postmortem.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version, and record
+the stage as degraded. During a live incident, prefer the degraded inline version over
+stopping to install anything.
+
+## Quality bar
+
+- **Every alert has a runbook entry.** An alert that pages someone with no procedure is an interruption, not a signal.
+- **The postmortem ends in runbook deltas.** Analysis with no procedural change is a story about an outage.
+- **Comms match the incident's actual stage.** Detect, mitigate, and resolve have different audiences and different truths.
+- **Blameless means blameless.** Naming a person is a defect in the postmortem; naming a missing guardrail is the point.
+
+## Anti-patterns to avoid
+
+- ❌ **Writing the runbook before the observability plan.** Procedures for alerts that do not exist, and none for the alerts that do.
+- ❌ **Skipping `learn` because the incident was small.** Small incidents are where the cheap runbook deltas are.
+- ❌ **Guessing impact numbers to finish the postmortem.** State the gap; a postmortem's value is entirely in its accuracy.
+- ❌ **Replaying `instrument` during a live incident.** Enter at `respond`; the loop is not a checklist to complete in order.

package/loops/operate/loop.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "RFC-0028. The only loop whose failures are irreversible and live. Its feedback edge is real and already documented in the repo: postmortem-generator emits runbook deltas phrased as edits for runbook-generator.",
+  "name": "operate",
+  "version": "0.1.0",
+  "description": "Take a shipped service through detection, response, and learning — instrument it, write the runbook, communicate the incident, then feed the postmortem's deltas back into the runbook. Use when the user is preparing to run a service, is in an incident, or is writing a postmortem.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "instrument",
+      "type": "generate",
+      "intent": "Decide what is measured and what pages a human. You cannot respond to what you never detected.",
+      "skills": ["observability-plan"]
+    },
+    {
+      "id": "document",
+      "type": "generate",
+      "intent": "Write the procedure the on-call follows at 3am, per alert the previous stage defined.",
+      "skills": ["runbook-generator"]
+    },
+    {
+      "id": "respond",
+      "type": "generate",
+      "intent": "Communicate during the incident, to the audience that needs it, at the stage the incident is actually in.",
+      "skills": ["incident-comms"]
+    },
+    {
+      "id": "learn",
+      "type": "verify",
+      "intent": "Analyse blamelessly and emit runbook deltas. An incident that changes no procedure has not been learned from.",
+      "skills": ["postmortem-generator"],
+      "gate": {
+        "id": "G3",
+        "kind": "human",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "BLOCKED"],
+        "revise_to": "document"
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.11.6",
+  "version": "0.11.7",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship \u2014 diagrams, ADRs, PRDs, runbooks, decks, reviews \u2014 installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/skills/architecture-diagrams/manifest.json

@@ -14,6 +14,9 @@
   "related": [
     "figma-diagrams"
   ],
+  "handoff": [
+    { "to": "figma-diagrams", "when": "the diagram needs to live where designers work", "purpose": "Push the rendered diagram into Figma.", "fallback": "If figma-diagrams is absent, leave the Mermaid source and say it needs manual import; never fabricate a Figma URL." }
+  ],
   "tags": [
     "diagrams",
     "mermaid",

package/skills/bug-triage/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["feature-implement-loop", "postmortem-generator", "user-story-splitter"],
+  "handoff": [
+    { "to": "feature-implement-loop", "when": "the defect is reproduced and scoped", "purpose": "Fix the triaged defect through the same capped loop a story gets.", "fallback": "If feature-implement-loop is absent, fix inline with a regression test that fails before the fix." }
+  ],
   "tags": ["bug-triage", "bug-report", "ticket", "qa", "repro", "severity"],
   "model": { "tier": "standard", "rationale": "Extraction plus judgment calls (severity vs priority, hypothesis ranking) — same shape as brief-intake: above light, below heavy." }
 }

package/skills/design-doc/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["architecture-diagrams"],
+  "handoff": [
+    { "to": "architecture-diagrams", "when": "the design is written and needs rendering", "purpose": "Render the prose as a diagram that must not disagree with it.", "fallback": "If architecture-diagrams is absent, emit Mermaid inline and check every node against a claim in the doc." }
+  ],
   "tags": ["design-doc", "documentation", "engineering", "review"],
   "model": { "tier": "standard", "rationale": "Synthesizes a design doc from a brief. Escalates to opus on big or genuinely contested inputs." }
 }

package/skills/feature-implement-loop/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["design-doc", "devils-advocate", "doc-critique", "pre-merge-review"],
+  "handoff": [
+    { "to": "pre-merge-review", "when": "the code exists and the question is whether it can merge", "purpose": "Judge the diff that now exists against a mechanical gate.", "fallback": "If pre-merge-review is absent, run the repo's own lint and tests and honour the exit code; do not self-certify." }
+  ],
   "tags": ["dev-workflow", "implementation", "tdd", "acceptance-criteria", "adversarial", "self-correcting", "code-generation"],
   "model": { "tier": "standard", "rationale": "Code + test generation against acceptance criteria. The adversarial pass delegates to devils-advocate (heavy) where available; the loop itself is generation." }
 }

package/skills/incident-comms/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["postmortem-generator", "runbook-generator"],
+  "handoff": [
+    { "to": "postmortem-generator", "when": "the incident is resolved", "purpose": "Analyse blamelessly and emit runbook deltas.", "fallback": "If postmortem-generator is absent, write the timeline, the contributing factors, and the procedural changes inline." }
+  ],
   "tags": ["incident", "communication", "status-page", "outage", "stakeholder", "sre"],
   "model": { "tier": "standard", "rationale": "Audience-segmented message generation under a strict don't-retract discipline. Same shape as exec-summary/audience-profile — translation and altitude, not adversarial reasoning." }
 }

package/skills/nfr-spec/manifest.json

@@ -6,6 +6,11 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["capacity-cost-model", "design-doc", "prd-draft", "test-plan-generator", "threat-model"],
+  "handoff": [
+    { "to": "design-doc", "when": "the quality targets are set", "purpose": "Design against the stated numbers rather than against taste.", "fallback": "If design-doc is absent, restate each target beside the design choice that serves it." },
+    { "to": "threat-model", "when": "the design has a trust boundary worth attacking", "purpose": "Attack the design before it is ratified.", "fallback": "If threat-model is absent, list the trust boundaries and one abuse case per boundary inline." },
+    { "to": "test-plan-generator", "when": "the targets need verifying, not just stating", "purpose": "Turn each quality target into a coverage entry.", "fallback": "If test-plan-generator is absent, name the test that would falsify each target." }
+  ],
   "tags": ["nfr", "requirements", "slo", "performance", "availability", "quality-attributes"],
   "model": { "tier": "standard", "rationale": "Rubric-driven sweep with archetype defaults; the judgment is calibrating targets to business reality. Bounded by the catalog; escalate via ambiguous-input on contested SLOs." }
 }

package/skills/observability-plan/manifest.json

@@ -6,6 +6,10 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["capacity-cost-model", "incident-comms", "nfr-spec", "postmortem-generator", "runbook-generator", "success-metrics"],
+  "handoff": [
+    { "to": "runbook-generator", "when": "the alerts are defined and each needs a procedure", "purpose": "Write the procedure the on-call follows per alert.", "fallback": "If runbook-generator is absent, write one numbered procedure per alert inline." },
+    { "to": "incident-comms", "when": "detection fired and an audience needs telling", "purpose": "Communicate at the stage the incident is actually in.", "fallback": "If incident-comms is absent, state the stage, the impact, and the next update time inline." }
+  ],
   "tags": ["observability", "slo", "sli", "alerting", "monitoring", "sre"],
   "model": { "tier": "standard", "rationale": "Methodology synthesis against fixed SRE practices (golden signals, burn-rate alerting, pillar split). SLO calibration needs judgment but is bounded; escalate via ambiguous-input on contested reliability targets." }
 }

package/skills/output-hygiene/manifest.json

@@ -15,6 +15,9 @@
     "doc-critique",
     "ai-usage-policy"
   ],
+  "handoff": [
+    { "to": "doc-critique", "when": "the surface is clean and the draft is still weak", "purpose": "The fault is the argument, not the residue.", "fallback": "If doc-critique is absent, name the weakest claim and what evidence it needs." }
+  ],
   "tags": [
     "hygiene",
     "cleanup",

package/skills/postmortem-generator/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["runbook-generator"],
+  "handoff": [
+    { "to": "runbook-generator", "when": "the postmortem produced runbook deltas", "purpose": "Apply the deltas as edits to the existing runbook.", "fallback": "If runbook-generator is absent, phrase each delta as a concrete before/after edit so a human can apply it." }
+  ],
   "tags": ["postmortem", "incident", "rca", "sre", "blameless", "outage"],
   "model": { "tier": "standard", "rationale": "Synthesizes a structured doc from incident notes. Contributing-factor chains need judgment but are bounded; escalate via large-input on huge scrollbacks." }
 }

package/skills/prd-draft/manifest.json

@@ -6,6 +6,11 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["brief-intake", "bug-triage", "business-case", "design-doc", "nfr-spec", "success-metrics", "user-story-splitter"],
+  "handoff": [
+    { "to": "nfr-spec", "when": "the functional requirements are agreed", "purpose": "Set the quality targets the design will be judged against.", "fallback": "If nfr-spec is absent, state latency, availability and scale targets inline as numbers, not adjectives." },
+    { "to": "user-story-splitter", "when": "the requirements are ready to become units of work", "purpose": "Split into vertically-sliced stories with acceptance criteria.", "fallback": "If user-story-splitter is absent, slice inline and give each story acceptance criteria a test can assert." },
+    { "to": "design-doc", "when": "the what is agreed and the how is open", "purpose": "Design the system that satisfies these requirements.", "fallback": "If design-doc is absent, write the approach, the alternatives, and the trade-offs inline." }
+  ],
   "tags": ["prd", "requirements", "product", "discovery", "moscow", "non-goals"],
   "model": { "tier": "standard", "rationale": "Synthesizes a structured requirements doc from a brief. The solution-language discipline needs care; bounded by the template. Escalate via ambiguous-input on contested scope." }
 }

package/skills/pre-merge-review/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["feature-implement-loop", "devils-advocate", "council-review", "doc-critique"],
+  "handoff": [
+    { "to": "council-review", "when": "the blocker is a design disagreement, not a defect", "purpose": "Adjudicate the disagreement outside the diff.", "fallback": "If council-review is absent, state each position and its strongest counter inline, and name the crux the decision turns on." }
+  ],
   "tags": ["dev-workflow", "code-review", "pre-merge", "quality-gate", "subagents", "production-readiness"],
   "model": { "tier": "standard", "rationale": "Coordination: runs a deterministic gate script, dispatches the (heavy) reviewer subagents, and renders a rule-based go/no-go. The adversarial reasoning is delegated to the panel, so the skill itself is orchestration, not deep judgment." }
 }

package/skills/requirements-interview/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["brief-intake", "decision-log", "prd-draft"],
+  "handoff": [
+    { "to": "brief-intake", "when": "the interview is done and the notes are raw", "purpose": "Collect the transcript into a tagged brief before any generator sees it.", "fallback": "If brief-intake is absent, tag each captured field [explicit]/[implied]/[inferred]/[missing] inline and say which downstream skill the brief is shaped for." }
+  ],
   "tags": ["discovery", "interviews", "requirements", "elicitation", "stakeholders", "user-research"],
   "model": { "tier": "standard", "rationale": "Question banks are rubric-shaped, but ranking by design impact and deriving falsification conditions for the specific feature is synthesis — above light." }
 }

package/skills/strategy-analysis/manifest.json

@@ -6,6 +6,10 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["business-case", "okr-cascade", "prfaq", "tech-comparison-matrix"],
+  "handoff": [
+    { "to": "tech-comparison-matrix", "when": "the options are named and need comparing on stated criteria", "purpose": "Score the named options against weighted criteria.", "fallback": "If tech-comparison-matrix is absent, build a plain criteria-by-option table inline and state the weights." },
+    { "to": "business-case", "when": "the direction is chosen and needs costing before approval", "purpose": "Cost the chosen option against a do-nothing baseline.", "fallback": "If business-case is absent, state option 0 and the three cost layers (build, run, opportunity) inline." }
+  ],
   "tags": ["strategy", "swot", "tows", "five-forces", "pestle", "competitive-analysis", "market-analysis"],
   "model": { "tier": "heavy", "rationale": "Framework selection plus evidenced multi-factor judgment ending in a ranked, committal verdict. Cheaper models fill cells with generic filler, skip the TOWS crossings, and refuse to take a side. Never downgrade." }
 }

package/skills/user-journey-map/manifest.json

@@ -6,6 +6,10 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["architecture-diagrams", "prd-draft", "reverse-architecture", "success-metrics", "user-story-splitter"],
+  "handoff": [
+    { "to": "prd-draft", "when": "a friction point on the journey is worth fixing", "purpose": "Turn the named friction into numbered requirements.", "fallback": "If prd-draft is absent, write the requirements inline as numbered, testable statements and note that prd-draft in skilldrop would structure them." },
+    { "to": "success-metrics", "when": "the fix needs a measure before it is built", "purpose": "Design the measurement for the journey step being changed.", "fallback": "If success-metrics is absent, state one baseline and one target per fixed step inline." }
+  ],
   "tags": ["journey-map", "customer-experience", "ux", "touchpoints", "mermaid", "personas"],
   "model": { "tier": "standard", "rationale": "Structured synthesis into a fixed four-row stage model plus bounded ranking judgment. Escalate via ambiguous-input when the persona or outcome is contested or research inputs conflict." }
 }

package/skills/user-story-splitter/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["feature-implement-loop"],
+  "handoff": [
+    { "to": "feature-implement-loop", "when": "a story has acceptance criteria a test can assert", "purpose": "Implement the slice through a capped generate-verify loop.", "fallback": "If feature-implement-loop is absent, implement inline but still challenge the result and cap the rounds at three." }
+  ],
   "tags": ["user-stories", "agile", "backlog", "acceptance-criteria", "planning", "sprint"],
   "model": { "tier": "standard", "rationale": "Decomposes an epic into INVEST slices with testable ACs. Structured synthesis; escalation rules cover large or contradictory PRDs." }
 }