skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/solution-architect/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.2.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"]
+    }
+  ]
+}

skilldrop_cli/data/packs/solution-architect/pack.json

@@ -0,0 +1,65 @@
+{
+  "description": "Design-phase artifacts: diagrams, decision records, design docs, contracts, schemas, threat models, and the reviews that gate them.",
+  "display_name": "Solution architect",
+  "keywords": ["architecture", "adr", "design-doc", "threat-model", "diagrams"],
+  "links": {
+    "documentation": "https://sananthanarayan.github.io/skilldrop/packs/solution-architect/"
+  },
+  "maintainers": [
+    {
+      "name": "sananthanarayan"
+    }
+  ],
+  "first-value": {
+    "audience-posture": "technical",
+    "prerequisites": [],
+    "starter-task": "Record an architecture decision your team already made",
+    "starter-prompt": "Write an ADR: we're moving our session store from Redis to DynamoDB. We considered staying on Redis, DynamoDB, and Postgres; we chose DynamoDB for managed scaling and lower ops load.",
+    "verification": "adr-generator returns an ADR with context, the options considered with their trade-offs, the decision, and its consequences.",
+    "recovery": "If adr-generator does not activate, ask for it by name (\"use adr-generator\") and check that its folder exists in your skills folder (`~/.claude/skills/` by default)."
+  },
+  "requires": ["core"],
+  "journey": {
+    "when": "You have an agreed requirement and need to decide how to build it, then record that decision.",
+    "you_bring": [
+      "the ratified requirement or PRD",
+      "known constraints: traffic, data, compliance, existing systems",
+      "the options you are weighing, if you already have them"
+    ],
+    "time": "1–3 hours",
+    "steps": [
+      {
+        "skill": "nfr-spec",
+        "you_do": "Describe the feature or system and what you know about load, data and users.",
+        "you_get": "Every non-functional category set to a measurable target, an explicit n/a, or a tagged default."
+      },
+      {
+        "skill": "design-doc",
+        "you_do": "Give it the requirement and the NFR targets.",
+        "you_get": "A design doc with problem, goals and non-goals, options considered, the recommended approach, risks and rollout."
+      },
+      {
+        "skill": "architecture-diagrams",
+        "you_do": "Ask for diagrams of the recommended approach from the design doc.",
+        "you_get": "Mermaid, PlantUML or C4 diagrams that must agree with the doc."
+      },
+      {
+        "skill": "threat-model",
+        "you_do": "Hand it the design doc and diagrams.",
+        "you_get": "A STRIDE threat model with assets and trust boundaries, attack scenarios at each boundary crossing, and ranked, verifiable mitigations."
+      },
+      {
+        "skill": "council-review",
+        "you_do": "Put the design and threat model in front of the review panel.",
+        "you_get": "Independent positions from each seat, the named cruxes, and a Chair's verdict that records dissent and what would change the decision.",
+        "decide": "Gate G1: PROCEED or PROCEED WITH CONDITIONS moves on; REVISE sends you back to the design doc; SPLIT or RECONSIDER leaves the loop."
+      },
+      {
+        "skill": "adr-generator",
+        "you_do": "Ask for the ADR once the panel has agreed, including any conditions it set.",
+        "you_get": "An ADR in MADR or Nygard format with context, the options and why each was rejected, the decision and its consequences."
+      }
+    ],
+    "you_end_with": "NFR targets, a design doc with matching diagrams, a threat model, the panel's verdict, and an ADR that carries its conditions."
+  }
+}

skilldrop_cli/data/packs/solution-architect/skills/adr-generator/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: adr-generator
+description: Generate an Architecture Decision Record (ADR) from a context-decision-consequences brief. Supports the two common formats — MADR (Markdown Any Decision Records) and Michael Nygard's original ADR template. Use whenever the user wants to capture an architectural decision, write an ADR, or document a "we decided X because Y" moment.
+---
+
+# adr-generator
+
+You help the user produce a clean, properly-numbered Architecture Decision Record.
+
+## How to respond
+
+1. **Pick the format.** Default to **MADR** (richer, has decision drivers + pros/cons per option). Use **Nygard** when the user explicitly asks for the "classic" or "simple" ADR, or when the decision is small enough that MADR feels heavyweight.
+
+2. **Gather the essentials.** Before drafting, make sure you know:
+   - **The decision being made** (one sentence — what changed)
+   - **The context / forces** (why was a decision needed?)
+   - **The options that were considered** (at least 2 — if only one option exists, this isn't really a decision)
+   - **Why the chosen option won** (the trade-off)
+
+   Ask at most 2 clarifying questions if essentials are missing. Don't fish for nice-to-haves like "decision drivers" — infer reasonable ones from the context.
+
+3. **Number it correctly.** ADRs are numbered sequentially starting at `0001`. Ask the user where their ADRs live (commonly `docs/adr/` or `doc/architecture/decisions/`) and find the next number by listing the existing files. If no ADRs exist yet, start at `0001`.
+
+4. **Pick the filename.** Use the slug form: `NNNN-short-title-in-kebab-case.md`. Examples:
+   - `0001-record-architecture-decisions.md`
+   - `0007-use-postgres-as-primary-datastore.md`
+   - `0014-adopt-event-driven-checkout.md`
+
+5. **Output.** Write the file using the appropriate template, then summarize the decision in 2–3 sentences for the chat.
+
+## Templates
+
+- [`templates/madr.md`](templates/madr.md) — MADR 3.0 format (recommended)
+- [`templates/nygard.md`](templates/nygard.md) — Nygard's original (simpler, 4 sections)
+
+## Quality bar
+
+- **Status** must be one of: `Proposed`, `Accepted`, `Deprecated`, `Superseded by ADR-NNNN`. Default to `Proposed` unless the user says it's already been agreed. "We decided", "we chose" and "we're going with" all say it was agreed: write `Accepted`.
+- **Title is a noun phrase**, not a verb phrase. ✅ "Postgres as the primary datastore" — ❌ "Decide what database to use".
+- **Consequences must include trade-offs, not just upsides.** If you can't list a downside, the decision wasn't real.
+- **Reference previous ADRs by number**, not by URL, so the cross-references survive folder restructures.
+- **Don't editorialize.** An ADR records what was decided, not what you (the AI) think was wisest.
+
+## Anti-patterns to avoid
+
+- ❌ Writing an ADR for a non-decision ("use industry best practices"). If the title could appear in a textbook, it's not a decision record.
+- ❌ Listing 6 options when only 2 were seriously considered. Cut the noise.
+- ❌ "Pros: it's better" with no "Cons:" line.
+- ❌ Filling in deciders, dates, drivers or history the user didn't give. Leave the field out or mark it `[not supplied]`; an invented fact in a decision record gets cited later as the reason.
+- ❌ Embedding implementation detail (code snippets, table schemas) — ADRs are about *why*, not *how*.

skilldrop_cli/data/packs/solution-architect/skills/adr-generator/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Write an ADR for this decision",
+    "should_trigger": true
+  },
+  {
+    "query": "Document the 'we decided X because Y' moment as an architecture decision record",
+    "should_trigger": true
+  },
+  {
+    "query": "Capture this architectural decision in MADR format",
+    "should_trigger": true
+  },
+  {
+    "query": "We picked Postgres over Dynamo — record the decision properly",
+    "should_trigger": true
+  },
+  {
+    "query": "Extract the decisions and owners from these meeting notes",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a full engineering design doc for this feature",
+    "should_trigger": false
+  },
+  {
+    "query": "Critique the ADR I already wrote",
+    "should_trigger": false
+  },
+  {
+    "query": "Convene a council to decide which database we should use",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/solution-architect/skills/adr-generator/evals/evals.json

@@ -0,0 +1,17 @@
+{
+  "skill_name": "adr-generator",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write an ADR: we decided to use Postgres as our primary datastore instead of DynamoDB, because our access patterns are relational and the team already operates Postgres.",
+      "assertions": [
+        "Status is one of Proposed / Accepted / Deprecated / Superseded by ADR-NNNN, defaulting to Proposed unless the user says it was agreed",
+        "Title is a noun phrase naming the decision, not a verb phrase naming the activity",
+        "Consequences include real trade-offs and downsides, not only upsides",
+        "The alternatives considered each carry a why-not, not just a description",
+        "The chosen format is MADR by default; Nygard only when explicitly requested",
+        "No invented context — facts not supplied by the user are marked rather than fabricated"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/solution-architect/skills/adr-generator/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "adr-generator",
+  "version": "0.1.1",
+  "description": "Generate an Architecture Decision Record (ADR) from a context-decision-consequences brief. Supports the two common formats — MADR (Markdown Any Decision Records) and Michael Nygard's original ADR template. Use whenever the user wants to capture an architectural decision, write an ADR, or document a \"we decided X because Y\" moment.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [],
+  "tags": ["adr", "documentation", "decisions", "architecture"],
+  "model": { "tier": "standard", "rationale": "Structures a decision into MADR/Nygard. Bounded judgment, not adversarial." }
+}

skilldrop_cli/data/packs/solution-architect/skills/adr-generator/templates/madr.md

@@ -0,0 +1,56 @@
+# {Short noun phrase — the decision, not the question}
+
+- Status: {Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](nnnn-...md)}
+- Date: {YYYY-MM-DD}
+- Deciders: {names or roles}
+- Tags: {comma-separated, optional}
+
+## Context and Problem Statement
+
+{Two to four sentences. What forces are at play? Why does a decision need to be made *now*? Use neutral language — the context is the same regardless of which option is chosen.}
+
+## Decision Drivers
+
+- {Driver — e.g. "must run on existing AWS estate"}
+- {Driver — e.g. "team has 5 years of Postgres expertise"}
+- {Driver — e.g. "must support 10k QPS at p99 < 50ms"}
+
+## Considered Options
+
+- {Option 1}
+- {Option 2}
+- {Option 3}
+
+## Decision Outcome
+
+Chosen option: **{Option N}**, because {one-sentence rationale tied to the decision drivers above}.
+
+### Consequences
+
+- ✅ {Positive — what becomes easier?}
+- ⚠️ {Trade-off — what's acceptable but worth noting?}
+- ❌ {Negative — what becomes harder or constrains future choices?}
+
+## Pros and Cons of the Options
+
+### {Option 1}
+
+- ✅ Good, because {reason}
+- ✅ Good, because {reason}
+- ❌ Bad, because {reason}
+
+### {Option 2}
+
+- ✅ Good, because {reason}
+- ❌ Bad, because {reason}
+- ❌ Bad, because {reason}
+
+### {Option 3}
+
+- ✅ Good, because {reason}
+- ❌ Bad, because {reason}
+
+## Links
+
+- {Related ADR — e.g. [ADR-0003](0003-...md)}
+- {External reference — e.g. RFC, vendor doc, benchmark}

skilldrop_cli/data/packs/solution-architect/skills/adr-generator/templates/nygard.md

@@ -0,0 +1,19 @@
+# {NNNN}. {Short noun phrase — the decision}
+
+Date: {YYYY-MM-DD}
+
+## Status
+
+{Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](nnnn-...md)}
+
+## Context
+
+{What is the issue that we're seeing that is motivating this decision or change? Describe the forces at play, including technological, political, social, and project-local. Use value-neutral language.}
+
+## Decision
+
+{What is the change that we're actually proposing or doing?}
+
+## Consequences
+
+{What becomes easier or more difficult to do because of this change? List both positive and negative consequences. If you can't list a downside, you haven't thought hard enough.}

skilldrop_cli/data/packs/solution-architect/skills/api-contract-draft/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: api-contract-draft
+description: Draft an OpenAPI 3.1 contract from a feature brief or story — resource-oriented paths, a full error catalog (RFC 9457), pagination/idempotency/versioning decided not deferred, examples on every operation, plus a decisions log so review argues choices instead of YAML. Use when the user wants to design an API, draft an OpenAPI/Swagger spec, define request/response shapes, or agree a contract between frontend/backend or two teams before code.
+---
+
+# api-contract-draft
+
+Produces the contract *before* the code — a valid OpenAPI 3.1 document two teams can argue about and then build against in parallel. The YAML is half the artifact; the other half is the **decisions log**, because reviewers should debate "cursor vs offset pagination", not line 240. Designs new contracts; documenting an existing API is `guide-builder`'s job.
+
+## How to respond
+
+1. **Extract the resources from the brief.** Nouns the API owns, their relationships, and their lifecycle (who creates, what mutates, is delete real or soft). Ask at most 2 questions, and spend them on consumer shape ("who calls this — our SPA, partners, both?") and write semantics ("can a refund be requested twice?") — the two answers that change the contract most. Everything else: pick the convention from [`reference.md`](reference.md) and tag the choice `[assumption]` in the decisions log.
+
+2. **Apply the house conventions** (full detail in [`reference.md`](reference.md)) — deviate only when the brief forces it, and log the deviation:
+   - **Paths**: plural-noun resources, no verbs — ✅ `POST /refunds` ❌ `POST /createRefund`; nesting one level max, then flatten with filters
+   - **Errors**: RFC 9457 `application/problem+json`, every 4xx the operation can return enumerated with a stable machine-readable `code`; no bare unexplained 500
+   - **Pagination**: cursor-based by default (`cursor` + `limit`, response carries `next_cursor`); offset only with a logged reason
+   - **Idempotency**: every unsafe POST takes `Idempotency-Key`; PUT/DELETE idempotent by construction
+   - **Versioning**: URL major version (`/v1/`), additive changes don't bump, breaking changes do — the policy sentence goes in the spec's `description`
+   - **Auth**: a `securityScheme` exists and every operation declares its requirement — including the explicitly-public ones
+
+3. **Type every field like a reviewer will reject sloppiness.** Formats (`uuid`, `date-time`, `int64`), constraints (`maxLength`, `minimum`, `enum`, `pattern` for codes), required vs optional explicit on every schema, money as integer minor units (never float), timestamps UTC ISO-8601. A schema that's all bare `type: string` is a draft of a draft.
+
+4. **Give every operation a realistic example** — request and the 2xx response, with values that look like production (`"cur_9f3k..."`, not `"string"`). Examples are where shape disagreements surface; they're the cheapest review tool in the document.
+
+5. **Emit three sections in one message**:
+   1. **Decisions log** — table of every contract decision (resource naming, pagination, error model, versioning, auth, the `[assumption]`s) with a one-line rationale each
+   2. **The OpenAPI 3.1 YAML** — complete and valid: `info` (with the versioning policy), `servers`, `components.securitySchemes`, `components.schemas` (including the `Problem` schema), paths with examples
+   3. **Open questions** — the unknowns that block freezing the contract, each with who can answer it
+   Start from [`templates/openapi-skeleton.yaml`](templates/openapi-skeleton.yaml).
+
+6. **For event/queue contracts** (the brief says "publish", "consume", "webhook out"): same discipline, AsyncAPI-shaped — channel name, payload schema with the same typing rigor, delivery semantics stated (at-least-once is the default; say it), and the consumer-retry/DLQ expectation in the channel description.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the house conventions: naming, errors, pagination, idempotency, versioning, field-typing rules
+- [`templates/openapi-skeleton.yaml`](templates/openapi-skeleton.yaml) — valid 3.1 starting point with `Problem` schema, security scheme, and one fully-worked resource
+
+## Quality bar
+
+- **The YAML validates.** OpenAPI 3.1, parseable, refs resolve. A contract that doesn't lint is a sketch.
+- **Every operation enumerates its 4xx set** with stable `code` values a client can switch on. "400: Bad Request" alone is an unwritten error contract.
+- **Every decision in the log has a rationale**, and every deviation from `reference.md` conventions is logged as a decision — silent deviation is how two services end up with three pagination styles.
+- **Examples look like production data.** `"id": "string"` in an example means nobody pictured a real call.
+- **No float money, no naked timestamps, no stringly-typed enums.** The three classic contract regrets, all preventable at draft time.
+- **Unsafe operations state their idempotency story.** A reviewer can answer "what happens on retry?" for every POST.
+
+## When to use this skill
+
+- ✅ Designing a new API or new resource before implementation
+- ✅ Frontend and backend (or two teams) need a contract to build against in parallel
+- ✅ A story from `user-story-splitter` whose slice is "expose X over the API"
+- ✅ Drafting the webhook/event contract a partner will consume
+
+## When NOT to use this skill
+
+- ❌ Documenting an API that already exists — that's `guide-builder` (reference archetype)
+- ❌ Choosing REST vs GraphQL vs gRPC — that's `tech-comparison-matrix`; this skill starts after
+- ❌ Reviewing a contract someone else drafted — `doc-critique` or `council-review`
+- ❌ Generating server/client code from the spec — hand the frozen contract to the codegen tool
+
+## Anti-patterns to avoid
+
+- ❌ **RPC verbs in paths** (`/getUser`, `/doRefund`). The resource model is the contract's spine; verbs mean it was never designed.
+- ❌ **The 200-with-error-body.** `200 {"success": false}` breaks every client's error handling; failures use failure status codes.
+- ❌ **Deferring pagination "until we need it".** Retrofitting pagination onto a shipped list endpoint is a breaking change; decide it at draft.
+- ❌ **One giant shared schema** reused for create-request, update-request, and response, with half the fields "ignored on input". Separate the shapes; optionality differs.
+- ❌ **YAML without the decisions log.** Reviewers nitpick property names and never see that offset pagination or float money slipped through.
+- ❌ **Contract churn after parallel build starts.** Once both sides build, every change is a versioned change — the open-questions section exists to drain *before* freezing, not after.

skilldrop_cli/data/packs/solution-architect/skills/api-contract-draft/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Draft the OpenAPI spec for this API",
+    "should_trigger": true
+  },
+  {
+    "query": "Write the REST contract for these endpoints",
+    "should_trigger": true
+  },
+  {
+    "query": "I need an API contract with a proper error catalog and pagination decided",
+    "should_trigger": true
+  },
+  {
+    "query": "Turn this user story into an OpenAPI 3.1 definition",
+    "should_trigger": true
+  },
+  {
+    "query": "Define the contract for this Kafka topic our team publishes",
+    "should_trigger": false
+  },
+  {
+    "query": "Design the Postgres schema and indexes for this feature",
+    "should_trigger": false
+  },
+  {
+    "query": "What latency and availability targets should this service have?",
+    "should_trigger": false
+  },
+  {
+    "query": "Review this API implementation for security bugs",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/solution-architect/skills/api-contract-draft/evals/evals.json

@@ -0,0 +1,18 @@
+{
+  "skill_name": "api-contract-draft",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Draft the OpenAPI contract for our orders API — clients need to create an order, fetch one, and list a customer's orders.",
+      "assertions": [
+        "The emitted YAML is parseable OpenAPI 3.1 and every $ref resolves",
+        "Paths are resource-oriented rather than RPC-style verbs in the URL",
+        "Every operation enumerates its 4xx set with stable machine-switchable code values — not a bare '400: Bad Request'",
+        "Errors follow RFC 9457 problem-details shape",
+        "Pagination, idempotency, and versioning are each decided explicitly rather than deferred",
+        "Every operation carries at least one example",
+        "Each decision in the log has a rationale, and any deviation from the skill's conventions is logged rather than made silently"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/solution-architect/skills/api-contract-draft/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "api-contract-draft",
+  "version": "0.1.0",
+  "description": "Draft an OpenAPI 3.1 contract from a feature brief or story — resource-oriented paths, a full error catalog (RFC 9457), pagination/idempotency/versioning decided not deferred, examples on every operation, plus a decisions log so review argues choices instead of YAML. Use when the user wants to design an API, draft an OpenAPI/Swagger spec, define request/response shapes, or agree a contract between frontend/backend or two teams before code.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["council-review", "doc-critique", "guide-builder", "tech-comparison-matrix", "user-story-splitter"],
+  "tags": ["api-design", "openapi", "contract-first", "rest", "swagger", "asyncapi"],
+  "model": { "tier": "standard", "rationale": "Schema synthesis against fixed conventions. The resource modeling needs judgment; the conventions bound it. Escalate via ambiguous-input on contested multi-team contracts." }
+}

skilldrop_cli/data/packs/solution-architect/skills/api-contract-draft/reference.md

@@ -0,0 +1,73 @@
+# api-contract-draft reference — house conventions
+
+These are defaults, not laws: deviate when the brief forces it, and log every deviation in the decisions table with its reason. An unlogged deviation is a bug in the contract.
+
+## Naming & paths
+
+- Resources are **plural nouns**: `/refunds`, `/payment-methods`. Kebab-case in paths, `snake_case` in JSON bodies.
+- No verbs in paths. State changes are either a `PATCH` of a status field or a **sub-resource action collection** when the transition has its own data/lifecycle: ✅ `POST /orders/{id}/cancellations` — ❌ `POST /orders/{id}/cancel` (acceptable only when the action is truly fire-and-forget and modeling it as a resource adds nothing — log it).
+- Nest **one level max** (`/customers/{id}/payment-methods`). Deeper relationships flatten to filters: ✅ `/invoices?customer_id=…` — ❌ `/customers/{id}/orders/{id}/invoices`.
+- IDs are opaque strings with a type prefix in examples (`"ord_8f4k2m"`) — prefixed IDs make logs and support tickets self-describing.
+
+## Errors — RFC 9457 `application/problem+json`
+
+Every error response is a `Problem`:
+
+```yaml
+Problem:
+  type: object
+  required: [type, title, status, code]
+  properties:
+    type: { type: string, format: uri, description: "Stable URI identifying the error class" }
+    title: { type: string, description: "Human summary, not for switching on" }
+    status: { type: integer }
+    code: { type: string, pattern: "^[a-z0-9_]+$", description: "Stable machine-readable code clients switch on" }
+    detail: { type: string }
+    errors: { type: array, description: "Field-level validation failures", items: { type: object, properties: { field: {type: string}, code: {type: string}, message: {type: string} } } }
+```
+
+- Enumerate **every 4xx the operation can produce**, each with its `code` values: `validation_failed`, `idempotency_key_reused`, `insufficient_funds`, …
+- `5xx`: document `500` once globally with a generic Problem; never invent per-operation 500 variants.
+- The `code` list is contract — adding one is additive; changing one is breaking.
+
+## Pagination, filtering, sorting
+
+- **Cursor pagination is the default**: request `?cursor=&limit=` (limit capped, cap stated), response `{ "data": [...], "next_cursor": "..." | null }`. Offset pagination only with a logged reason (e.g. "UI needs page numbers; dataset < 100k and stable").
+- Every list endpoint paginates **from day one** — even "small" lists; retrofitting is a breaking change.
+- Filters are query params named after the field (`?status=pending&created_after=…`). Sorting: `?sort=-created_at` (leading `-` = descending). Document which fields are filterable/sortable — "all of them" is never true.
+
+## Idempotency & retries
+
+- Every **unsafe POST** accepts `Idempotency-Key` (UUID, 24h retention stated). Same key + same body → replay the original response; same key + different body → `409` `idempotency_key_reused`.
+- `PUT` and `DELETE` are idempotent by construction; `DELETE` of a missing resource is `404` first time, `404` every time (not `204` — log if you choose tombstone semantics instead).
+- State the retry guidance in the operation description: which errors are retryable (`503`, `429` with `Retry-After`) and which never are (`4xx` except `429`).
+
+## Versioning
+
+- URL major version: `/v1/`. The policy sentence for `info.description`: *"Additive changes (new optional fields, new endpoints, new enum values where the field is documented as open) do not bump the version; removals, renames, type changes, and semantic changes do."*
+- Mark enums **open or closed** explicitly (`x-extensible-enum` note or description) — clients must know whether to tolerate unknown values.
+- Deprecation: `deprecated: true` + `Sunset` header mention + the replacement named in the description. No silent removals, ever.
+
+## Field typing rules
+
+| Concern | Rule |
+|---|---|
+| Money | Integer minor units + ISO-4217 `currency` field. Float money fails review. |
+| Timestamps | `type: string, format: date-time`, UTC, ISO-8601. Field names end `_at`. |
+| IDs | `type: string` opaque; never `integer` (leaks sequence, blocks resharding). |
+| Enums | `enum: [...]` with every value, plus open/closed declared. |
+| Free text | `maxLength` always — unbounded strings are a storage and abuse contract. |
+| Booleans | Name as predicate: `is_default`, `has_failed`. Never tri-state a boolean — use an enum. |
+| Optionality | `required` array on every object schema; absent ≠ null — pick one and state it. |
+| Quantities | `minimum`/`maximum` on every numeric the business bounds. |
+
+## Request/response shape separation
+
+Per resource, three schemas minimum: `{Resource}` (response), `{Resource}CreateRequest`, `{Resource}UpdateRequest`. Server-set fields (`id`, `created_at`, `status` when machine-driven) appear **only** in the response schema. The update schema has no required fields (PATCH semantics) unless the business requires atomically-paired fields — log that decision.
+
+## Event/webhook contracts (AsyncAPI-shaped)
+
+- Channel names: `{domain}.{resource}.{event}` past-tense — `payments.refund.completed`.
+- Payload: the same typing rigor; include `event_id` (UUID, for consumer dedupe), `occurred_at`, and a `schema_version`.
+- Delivery semantics stated per channel: default **at-least-once** — consumers must dedupe on `event_id`; say so in the channel description.
+- Webhooks out: HMAC signature header named, timestamp-skew window stated, retry schedule with backoff and a cap, and the consumer's expected 2xx contract ("respond 2xx within 10s; processing happens async on your side").