spec-reliability-implementation

What this skill does

# spec-reliability-implementation — a spec becomes a service that provably behaves like the spec

## ⚠️ Critical Constraints

- **The spec is the source of truth, not the code.** Every accepted behavior must
  trace to a spec clause. **Why:** code that "works" but diverges from the spec is
  a silent breach — the bug ships because nothing checks it against intent.

- **Acceptance examples come BEFORE implementation.** Write the executable
  examples (Given/When/Then) from the spec first, watch them fail, then make them
  pass. **Why:** examples written after the code only re-encode the code's
  behavior, so they can never catch a spec mismatch.
  ```
  WRONG: implement endpoint → write a test that asserts whatever it returns
  CORRECT: write Then "POST /orders twice with same key yields ONE order" → run (fails) → implement idempotency → run (passes)
  ```

- **Retries require idempotency; idempotency requires a key.** Never add a retry
  to a non-idempotent write. **Why:** retrying a non-idempotent call (double
  charge, duplicate order) turns a transient blip into a data-corruption bug.
  ```
  WRONG: client retries POST /charge on timeout → two charges
  CORRECT: client sends Idempotency-Key; server dedupes → one charge, retry-safe
  ```

- **An error path the spec names but the service does not handle is a FAIL,**
  not a TODO. **Why:** unhandled spec'd errors (bad input, downstream down, auth
  failure) are exactly the cases that page on-call.

## Why This Exists

Specs and services drift the moment code starts. The default failure mode is a
service that demos green but breaks the spec in the unhappy paths — the timeout,
the duplicate request, the malformed payload, the dependency outage. This skill
forces a closed loop: spec → executable acceptance examples → gated
implementation → reliability primitives (errors/retries/idempotency/observability)
→ a verification step that re-checks behavior against the spec before ship. The
output is not "it runs" — it's "it provably does what the spec says, including
when things go wrong."

## Quick Start

1. Read the spec. Extract a **clause inventory** — every testable assertion, each
   with an id (S1, S2, …). Mark each as happy-path, error-path, or
   reliability-property (retry/idempotency/observability).
2. Write `acceptance-examples.feature` — one scenario per clause, in Given/When/Then.
3. Run the examples; confirm they FAIL (red). No red, no proof.
4. Implement the smallest code to turn each scenario green, one clause at a time.
5. Add reliability primitives where the inventory demands them (see Methodology §4).
6. Run `bash {baseDir}/scripts/validate.sh` and the acceptance suite.
7. Produce `conformance-report.md`: clause → scenario → PASS/FAIL with evidence.

## Methodology

### 1. Spec → clause inventory (verification checkpoint: every testable line has an id)
Parse the spec into atomic, testable clauses. For each: id, quote, category
(happy / error / reliability / non-functional), and the observable that proves it.
A clause with no observable is not yet testable — push back on the spec, don't guess.

### 2. Clauses → acceptance examples (checkpoint: every clause maps to ≥1 scenario)
Write `acceptance-examples.feature` (Gherkin or your runner's equivalent). Each
scenario names its clause id in a tag or comment. Cover happy AND error paths.
Run the suite; it MUST be red before any implementation. Save the red run as evidence.

### 3. Implement against gates (checkpoint: one clause goes green per change, suite stays sorted)
Implement the thinnest slice to flip one scenario green. After each change, run
the suite + lint + type-check. Never batch — green one clause at a time so a
regression is attributable. Keep already-green scenarios green.

### 4. Reliability primitives (checkpoint: each property has a test that fails without it)
Add only what the inventory demands, each with a scenario that fails when removed:
- **Error handling:** map every spec'd error to a typed response/status. No bare
  500s for cases the spec anticipated. Validate input at the boundary.
- **Retries:** apply to idempotent operations only; bounded attempts, exponential
  backoff + jitter, a deadline/budget, and a circuit breaker for a failing
  dependency. Distinguish retryable (timeout, 503) from terminal (400, 409).
- **Idempotency:** dedupe writes by an idempotency key (client-supplied or derived);
  persist the key→result so a replay returns the original result, not a new effect.
- **Observability:** structured logs with a correlation/request id; metrics for
  rate / errors / latency (RED); a `/healthz` liveness and `/readyz` readiness
  probe; trace spans across the request and its downstream calls.

### 5. Verify behavior matches spec (checkpoint: conformance report is all-green or ship is blocked)
Run the full acceptance suite against the running service (not mocks of itself).
Exercise error paths and reliability properties deliberately (inject a timeout,
replay a request, kill a dependency). Build the conformance report. A single
unexplained FAIL blocks ship.

## Output Specification

- **`acceptance-examples.feature`** — executable Given/When/Then, one scenario per
  spec clause, tagged with the clause id.
- **`conformance-report.md`** — a table `clause id | spec quote | scenario |
  PASS/FAIL | evidence`, a reliability-properties section
  (errors/retries/idempotency/observability each PASS/FAIL), and a one-line
  ship/no-ship verdict.

## Quality Rubric

- Every spec clause in the inventory has at least one acceptance scenario, and
  every scenario names its clause id (no orphan scenarios, no untested clauses).
- The acceptance suite was demonstrably red before implementation and is green
  after, against the actually-running service (evidence captured both times).
- Each reliability property (error handling, retries, idempotency, observability)
  has a scenario that FAILS when the property is removed — proving the test bites.

## Examples

**Idempotent order creation (clause S4).**
Spec S4: "Creating an order is idempotent over the client's idempotency key."
Scenario: `Given a new idempotency key K / When I POST /orders with K twice /
Then exactly one order exists And both responses return the same order id`.
Run red (server ignores K) → implement key→result store → run green. The retry
scenario (S7: "client retries on 503") now composes safely on top of S4.

**Downstream outage (clause S9).**
Spec S9: "If the payment provider is unavailable, return 503 and do not create a
pending charge." Scenario injects a provider outage, asserts 503 + no charge row
and a logged correlation id. Without the circuit breaker + boundary check, the
scenario fails (leaks a pending charge) — proving the property is real.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Acceptance suite green on first run (never red) | Tests written after/around the code | Rewrite the scenario from the spec clause; confirm it fails on current code first |
| Retry causes duplicate side effects | Retrying a non-idempotent write | Add an idempotency key + key→result store before enabling retries |
| Service "passes" but breaks in prod on bad input | Error-path clauses never made into scenarios | Re-scan the spec for error clauses; add a scenario + typed handler per clause |
| Can't tell which change broke a scenario | Batched multiple clauses per change | Implement one clause per change; run the suite after each |
| Conformance report has unexplained FAIL | Behavior diverges from spec | Treat as ship-blocker; trace clause → code, fix the code OR escalate the spec ambiguity |

## See Also

| I need to… | Use | Reference |
|---|---|---|
| Run the structure self-check | `bash {baseDir}/scripts/validate.sh` (Execute) | — |
| Run this skill under Codex | Read [codex-parity.md](references/codex-parity.md) | references/codex-parity.md |