One job.
A little less friction.

---
name: alert-to-runbook
description: Turn one production alert and supplied system context into a short, evidence-based runbook. Use when an alert lacks useful first checks; not for a complete incident response policy.
metadata:
  title: An alert worth waking up for
  summary: Turn one noisy alert into a usable first-response note.
  category: operations
  related-post: calm-oncall
  updated: "2026-10-11"
---

# An alert worth waking up for

Read the alert expression, its evaluation window, and the system context supplied by the user. Separate the observed symptom from the suspected cause. If customer impact is unknown, say so instead of inventing it.

Write a compact runbook that contains:

- What fired, which service or tenant is affected, and what evidence establishes impact.
- The first two read-only checks, using real dashboard links or commands from the repository. Explain what each result would distinguish.
- A recovery action only when the repository or supplied operational notes support it, including its risk and a verification step. Otherwise name the missing information and the known escalation route.

Flag an alert that routinely resolves before intervention. Suggest a specific signal or window to investigate, without changing thresholds or declaring a safe value from insufficient history. Keep placeholders visibly unresolved; never fabricate dashboard URLs, owners, or production commands.

End with the one place the runbook should be linked from the alert configuration. Creating the note does not authorize executing recovery commands or changing monitoring.

---
name: dependency-tradeoff
description: Compare an existing solution, one dependency, and a small custom implementation for a specific engineering decision. Use before adding or replacing infrastructure or a library; not for broad technology rankings.
metadata:
  title: Before another dependency
  summary: Make the maintenance cost visible before picking a tool.
  category: architecture
  related-post: the-stack-your-agent-picks-is-a-product-decision
  updated: "2026-10-11"
---

# Before another dependency

Start with the behavior the product needs and the constraints already present in the repository. Read the lockfile, nearby implementations, and deployment configuration before recommending a new tool.

Compare keeping the current approach, one plausible dependency, and the smallest viable custom implementation. Omit an option only when a concrete constraint rules it out. Use current primary documentation for licensing, runtime support, and operational limits; label facts you could not verify.

For each viable option, explain who owns upgrades, failure recovery, credentials, data migration, and debugging in production. For custom code, include the operational behavior that a happy-path demo leaves out. For a dependency, include the exit path and the behavior that remains our responsibility.

Give a recommendation tied to the product constraint, the strongest reason against it, and the evidence that would change your mind. If a short experiment would settle the decision, describe its pass/fail condition. Keep the output short enough to paste into a PR discussion.

Do not install packages, provision services, or rewrite code as part of this comparison. Do not treat popularity, an agent's default choice, or repository familiarity as sufficient evidence.

---
name: retry-safety-review
description: Review one retrying operation for duplicate side effects, ambiguous timeouts, and unsafe retries. Use for a webhook handler, queue consumer, scheduled job, or agent tool call; not for a general code review.
metadata:
  title: Retry safety review
  summary: Find what happens when the same operation runs twice.
  category: reliability
  related-post: the-bug-is-in-the-harness-not-the-model
  updated: "2026-10-11"
---

# Retry safety review

Trace one operation from its entry point to its durable side effect. Identify who can retry it: the caller, HTTP client, queue, worker, or scheduler. Read the actual configuration; do not assume a library's defaults.

Walk through three cases against the code:

- The side effect succeeds but its acknowledgement is lost.
- Two deliveries with the same identity overlap.
- The process stops between the side effect and recording completion.

For each case, name the persisted state, the next attempt's behavior, and whether the result can be duplicated or lost. A check followed by a write is not atomic deduplication. A random key created on every attempt is not a stable operation identity. Consider retention: deduplication must outlast the possible redelivery window.

Return a small table of failure case, code evidence, and consequence. If there is an unsafe path, propose the smallest change and one test that reproduces the duplicate or lost result. Identify the transaction boundary explicitly; a database transaction cannot roll back a remote API call.

Do not add retries indiscriminately or claim exactly-once execution without evidence. If the remote service's idempotency contract is unknown, mark that dependency as unresolved. Review only; implement changes when requested.