/reviewing-operational-risk

name: ring:reviewing-operational-risk
description: "Reviewing a Go/TS service's operational risk by mapping integration failure points (external HTTP calls, queue consumers, outbound webhooks), simulating stuck intermediate states for each entity in a flow, and classifying each scenario into tiers — then emitting operational runbooks (Tier 2) or gap specs (Tier 3). Two entry modes: explore an existing codebase, or read a dev-cycle plan.md and epic artifacts. Use before production hardening, incident retros, or at dev-cycle end. Skip for prototypes, pure libraries, or when no integration boundaries exist."

Operational Risk Review

When to use

• Preparing a service for production and want to know what breaks when a flow gets stuck
• After a dev-cycle: pressure-test the newly built flows for recovery gaps
• Incident retro: formalize which failure modes have a rescue path and which do not
• You need operational runbooks or a backlog of "missing rescue mechanism" gap specs

Skip when

• Prototype / throwaway PoC not heading to production
• Pure library or SDK with no integration boundaries (no external calls, queues, or webhooks)
• Single-question check (use a targeted read instead of the full review)

Related

**Complementary:** ring:auditing-production-readiness (broad readiness scoring), ring:mapping-service-resources (resource inventory), ring:running-dev-cycle (optional end-of-cycle hook)

What this produces

For every failure scenario, a **tier** and an actionable artifact:

| Tier | Meaning | Output | |------|---------|--------| | **Tier 1** | The app resolves it itself — automatic retry, compensation, TTL/expiry, DLQ replay | Note only (documented as self-healing) | | **Tier 2** | An **external trigger exists** that unblocks it — an API call, an endpoint, a Console/UI action | **Operational runbook** with concrete steps | | **Tier 3** | **Gap** — no rescue path exists short of direct DB intervention | **Gap spec** (what's missing, who can act today, what should exist) |

Audience

The output is always written **for the developer running the skill** (tech lead or engineer). Runbooks assume operator access; gap specs assume backlog ownership.

---

How this skill runs: a hybrid (mechanical + judgement) flow

The review is split into two phases so the deterministic work is not left to the LLM:

**Phase 1 — mechanical (`scan-integration-points.mjs`, run by the dev):** A zero-dependency Node.js script traverses the target repo and finds integration boundaries (external HTTP calls, queue consumers, event publishers, outbound webhooks). For each point it heuristically records whether retry, DLQ, timeout, rollback/compensation, and idempotency patterns appear nearby. It emits a structured JSON report. It is generic: it runs on any Go or TypeScript/Node.js Lerian repo. This phase is repeatable and produces the same map every time.

**Phase 2 — judgement (this agent, from here on):** The agent takes the JSON as structured context, runs the confirmation dialogue, simulates stuck states, classifies Tier 1/2/3, and writes runbooks (T2) and gap specs (T3). This is the analysis that needs a human-in-the-loop and cannot be reduced to regex.

> **The developer runs the `.mjs` first and pastes/attaches its JSON output to > the agent before the dialogue begins.** In Mode A the agent uses that JSON as > the boundary map instead of re-deriving it by hand. See **Step 1 (Mode A)**.

---

Step 0: Determine entry mode

Ask the developer (or infer from context):

• **Mode A — Codebase explore:** review an existing service by scanning its integration boundaries.
• **Mode B — Plan context:** review flows just built in a dev-cycle by reading `plan.md` and the current cycle's epic artifacts, without exploring the whole repo.

If a `plan.md` (ring:writing-plans format) with an active cycle is present and the developer wants to review *what was just built*, prefer **Mode B**. Otherwise use **Mode A**.

---

Step 1 (Mode A): Map integration boundaries — run the scanner first

The boundary map is produced **mechanically** by the script, not by hand. The developer runs it against the target repo and gives the JSON to the agent:

# From the target repo root (any Go or TS/Node.js Lerian service):
node /path/to/reviewing-operational-risk/scan-integration-points.mjs . --out ops-risk-scan.json
# then paste/attach ops-risk-scan.json to the agent before the dialogue.

> **Monorepo / hexagonal Go — do NOT scan only the service subdir.** In a > hexagonal layout the outbound boundaries live in the imported `pkg/*` (or > shared adapter) packages, **not** under `apps/<svc>`. Scanning only > `apps/<svc>` returns a **false 0**. The scanner defends against this: given a > subdir it walks up to the repo/module root, scans the whole tree, and > attributes each boundary to its service via top-level dir. **Always run from > the repo root (or let the scanner expand to it) so `pkg/*` adapters and > `ports/out` methods are included.** If you must scan a single subdir, pass > `--no-repo-root` and expect the map to miss shared adapters. Whenever > `integration_points == 0` for a service that imports `ports/out`, the scanner > emits an explicit `warnings[]` entry — treat it as a scope error, not a clean > bill of health.

The scanner is **port-aware and adapter-aware**: each method of a `ports/out` interface is treated as a boundary candidate (`category: "outbound_port"`), and its resilience is inferred over the whole concrete **adapter file** — so an SDK adapter (e.g. `midazsdk.WithTimeout`, `DoWithRetry`) that never calls `net/http` directly is still detected. Resilience for Go line-matches is inferred over the **enclosing function**, not a fixed ±N-line window, so a retry/timeout wrapper elsewhere in the function still counts.

**Optional per-repo config (`.ops-risk.json`)** at the repo root tunes detection: `shared_adapter_dirs`, `http_wrapper_packages`, `outbound_port_globs`, and `exclude_handler