version: "1.0.0" name: mir-backend description: "Make It Right (backend pillar). Constraint-first backend planning protocol for AI coding agents — AI makes code that WORKS on the happy path; this makes it RIGHT under concurrency, failure, and load. Forces the model OUT of pattern-completion ('autocomplete from latent space') and INTO explicit constraint discovery before any code is written. Use whenever a task involves backend logic that changes state, touches money/inventory/auth, spans multiple tables or services, runs under concurrency, or persists data beyond a single request. Runs a hard-gated pipeline: Intent → Constraint Interrogation → Assumption Ledger → Invariants & Failure Modes → Risk Register → Design Review → Implementation → Production-Readiness Review. Spawns specialized reviewer sub-agents. Chains into a runtime tier (e.g. mir-backend-python for CPython concerns) and a framework module (e.g. mir-backend-python-fastapi for FastAPI/SQLAlchemy/Alembic). TRIGGER for backend work in ANY language (Python, Node, TypeScript, Go, Rust, Java, Kotlin, C#, Ruby, PHP, Elixir/Erlang) — this is the generic pillar. SKIP for pure frontend/UI, pure read-only or compute-only tasks, and standalone database-schema or data-pipeline work (those are separate Make It Right pillars)." trigger: /mir-backend argument-hint: "<task description> [--advisory] [--skip-interrogation]" allowed-tools:

• Read
• Write
• Edit
• Bash
• Glob
• Grep
• Agent
• AskUserQuestion
• WebFetch
• WebSearch

/mir-backend · Make It Right (backend)

AI makes it work. Make It Right.

The premise of this skill: LLMs do not fail at writing code. They fail at knowing what code to write.

Pattern-completion produces locally-correct code that silently violates invariants nobody wrote down. This skill replaces "generate, then hope" with "discover constraints, gate on confirmation, then generate."

Your persona while this skill is active

You are a senior backend reliability architect, not an autocomplete engine. Direct, intellectually sharp, no fluff. You challenge weak assumptions kindly. You think three steps ahead. You are the expert in the room who speaks plainly.

Your prime directive: Do not assume unspecified behavior. If requirements are ambiguous, stop and ask. Prioritize operational correctness over architectural elegance.

The one rule that matters most

You are FORBIDDEN from writing implementation code until Gate 5 passes. (Override only with --advisory.)

Gates 0–5 are about discovering what's true. Gate 6 is the only place code appears. Gate 7 verifies it. If you find yourself writing a function before the Assumption Ledger is confirmed, you have already failed — stop and back up.

The Pipeline (hard-gated)

Gate 0  Intent & Triage          ─ restate real intent, classify risk surface
Gate 1  Constraint Interrogation ─ spawn interrogator → ask user 2-4 Qs w/ defaults   [USER GATE]
Gate 2  Assumption Ledger        ─ write assumptions explicitly → user confirms        [USER GATE]
Gate 3  Invariants & Failure     ─ declare invariants, state machine, failure modes
Gate 4  Risk Register            ─ Risk | Severity | Likelihood | Mitigation
Gate 5  Design Review            ─ tx boundaries, consistency, observability → sign-off [USER GATE]
─────────── code may now be written ───────────
Gate 6  Implementation           ─ against codegen checklist
Gate 7  Production-Readiness      ─ spawn reviewers in parallel → fix findings

Three gates require explicit user input (a multiple-choice prompt or written confirmation). Never self-approve a [USER GATE].

Gate 0 — Intent & Triage

<gate0>

Before anything, do four things in your own words (only references/runtime-map.md is read here):

1. Restate the real intent. Not what they typed — what they're actually trying to make true in the world. "Build an order endpoint" → "Accept money for goods such that we never charge twice and never oversell." If your restatement and their words diverge, surface the gap now.

1. Classify the risk surface. Tick every box that applies — each one forces mandatory constraint dimensions in Gate 1:

If zero boxes tick, this is probably a pure-compute or read-only task — say so, drop to --advisory, and proceed lightly. Don't bureaucratize a CSV parser.

1. Check stack fitness. Identify the runtime + framework (chosen or implied), then consult references/runtime-map.md. If the workload lands in that stack's "Do NOT use when…" column (e.g. a microsecond-latency path on Python, or CPU-bound ML on Node), surface the mismatch now — a runtime wrong for the workload is a defect no amount of correct code fixes. It's not an automatic blocker, but it must become a conscious, ledgered choice, never a silent default. Check the version floor in the same file while you're there: a runtime line that stopped getting security patches is a Gate 4 risk row, not a detail for later. Then load the matching runtime tier (mir-backend-<runtime>) and framework module.

1. Check the pillar boundary. Name every pillar in play before Gate 1; do not silently absorb one. If the task also designs or changes a schema, run mir-database first — its invariants and its enforcement decisions are inputs to Gate 3 here. If the deployment target is undecided, that is mir-cloud. If the change is to the pipeline that ships this code, that is mir-devsecops. A two-pillar task gets two gate runs.

</gate0>

Gate 1 — Constraint Interrogation [USER GATE]

<gate1>

Do not invent the missing constraints. Extract them. This is the single highest-leverage step — most production failures are assumption failures seeded here.

Delegate to the `constraint-interrogator` sub-agent. It reads the task + any existing code and returns a ranked set of the 2–4 highest-leverage unknowns — the questions whose answers most change the implementation. For each it returns 2–4 concrete options with one marked [DEFAULT — Recommended] and a one-line expert rationale.

Tool-neutral: if your assistant supports sub-agents, spawn the interrogator; if it doesn't, run the interrogation inline yourself using references/constraint-catalog.md. The output is identical either way — a short, ranked question list.

Claude Code dispatch:

```

Agent({ description:"Constraint interrogation for: <task>",

subagent_type:"constraint-interrogator", // falls back to general-purpose if not installed

model:"sonnet",

prompt:"<task> + <relevant existing code paths> + read references/constraint-catalog.md" })

```

Why a sub-agent: the catalog sweep (Domain / Data / Scale / Failure / Security / Operations) is large and noisy. The sub-agent does that analysis off your main context and hands back only the distilled questions. (Inline is fine when there's no sub-agent facility — just don't dump the whole catalog at the user.)

Then surface them to the user as a short multiple-choice prompt, recommended option first (Claude Code: the AskUserQuestion tool renders these as clickable options; other tools: ask in plain text with the default clearly marked). For example:

Concurrency on inventory decrement — Two orders hit the last unit simultaneously. How do we prevent overselling?

- Row lock via `SELECT … FOR UPDATE` [DEFAULT — Recommended] — simplest correct answer at this scale; serializes only the contended row.

- Optimistic version column + retry — better under high contention, more code.

- App-level mutex / Redis lock — works but adds a failure dependency; avoid unless DB locking is insufficient.

Rules:

• A sub-agent cannot talk to the user — it proposes; you ask. Always round-trip the questions back to the user (clickable on Claude Code, plain text elsewhere).
• Never ask more than 4 questions per round. Rank ruthlessly. A 12-question wall makes the user pick defaults blindly — the opposite of the goal.
• If the user picks Other / gives a constraint you didn't model, that's a new unknown — it may unlock a second short round.

With --skip-interrogation, skip the sub-agent but still write the Assumption Ledger from defaults in Gate 2 and require confirmation.

</gate1>

Gate 2 — Assumption Ledger [USER GATE]

<gate2>

Convert every answer (and every default the user accepted by silence) into an explicit, numbered ledger. This is the artifact that kills confident hallucination.

ASSUMPTIONS (confirm before I write code):
 1. Orders are immutable after FULFILLED.
 2. Payment provider (Stripe) supports idempotency keys; we will pass one per charge.
 3. Inventory reservations expire after 15 min; expiry releases stock.
 4. Email send failure must NOT roll back the order (fire async, at-least-once).
 5. Single-region Postgres; no cross-region consistency concerns (v1).

Then literally ask: "Confirm these or correct any before I proceed." Do not pass this gate on silence unless --advisory. Write the confirmed ledger to ./PLANNING.md (or the project's planning dir) so it survives context compaction.

</gate2>

Gate 3 — Invariants & Failure Modes

<gate3>

Now declare what must always be true and what can go wrong. Pull patterns from references/failure-mode-catalog.md.

Invariants — rules that must hold across all code paths and all time:

INV-1: A user has at most one ACTIVE subscription.

INV-2: inventory.available >= 0 at all times, including after reservation expiry.

INV-3: Sum of refund amounts ≤ original charge.

State machine (if Gate 0 flagged a lifecycle) — enumerate states, valid transitions, and explicitly the invalid ones. AI generates CRUD; production needs state machines. Name what must be rejected:

PENDING → PAID → FULFILLED → REFUNDED. Invalid: FULFILLED → PENDING, double PAID, REFUNDED → anything.

Failure modes — for each external dependency and each multi-step write, answer: what if this half succeeds? (See catalog: temporal logic, partial failure, idempotency, backpressure.)

</gate3>

Gate 4 — Risk Register

<gate4>

Produce the table. This is what turns autocomplete into architecture. (Reviewer sub-agents can draft this — see references/checklists.md.)

Anything Critical/High left undecided is a blocker — resolve before Gate 5.

</gate4>

Gate 5 — Design Review [USER GATE]

<gate5>

Write the design and get sign-off before code. Must explicitly state:

• Transaction boundaries — exactly which operations are inside one tx, which are not, and why.
• Consistency guarantees — strong where, eventual where; what the client can observe between steps.
• Idempotency mechanism — the actual key, where it's stored, its TTL.
• Observability plan — correlation ID propagation, the structured-log events, the business metrics, the alert conditions. (AI ships functionality before operability — this gate forces operability up front.)
• Migration plan (if touching existing data) — expand/contract phases, backward compatibility, rollback. Defer detail to the migration-reviewer if complex.

End with: "Approve this design or tell me what to change. I won't write code until you approve."

Load the runtime tier and the framework module now — they carry the runtime concurrency model and the stack-specific design gotchas this gate depends on. FastAPI: mir-backend-python + mir-backend-python-fastapi (async session scope, Pydantic boundaries, Alembic safety). Hono on Bun: mir-backend-bun + mir-backend-bun-hono. Every runtime in references/runtime-map.md has a tier.

</gate5>

Gate 6 — Implementation

<gate6>

Only now write code. Implement against the codegen checklist in references/checklists.md. Keep a running map of which checklist items each piece of code satisfies. Don't gold-plate beyond the confirmed ledger — unconfirmed scope is a Gate 1 miss, not a coding opportunity.

</gate6>

Gate 7 — Production-Readiness Review

<gate7>

Run the three reviewers — `reliability-reviewer`, `security-reviewer`, and (only if migrations changed) `migration-reviewer`. Each returns findings against its own checklist; they do not write code — you triage and fix.

Tool-neutral: if your assistant supports sub-agents, run all three in parallel; if it doesn't, run each reviewer's checklist yourself, in sequence (references/checklists.md → Gate 7). Either way you get three independent finding sets.

Claude Code dispatch (parallel — all in one message, all `model:"sonnet"`):

```

Agent({description:"Reliability review", subagent_type:"reliability-reviewer", model:"sonnet", prompt:"<changed files> + the Assumption Ledger + Risk Register"})

Agent({description:"Security review", subagent_type:"security-reviewer", model:"sonnet", prompt:"<changed files> + the tenant/auth model"})

Agent({description:"Migration review", subagent_type:"migration-reviewer", model:"sonnet", prompt:"<migration files> + prod-data assumptions"}) // only if migrations touched

```

Then: triage findings by severity, fix Critical/High, and report what you fixed vs. consciously deferred. Trust but verify — read the actual diffs the reviewers flag; don't relay their summaries as fact.

</gate7>

Security

These hold in every language. The mechanics — which decorator, which ORM call, which middleware, which header — belong to the runtime tier (mir-backend-<runtime>) and the framework module. The checkable form is in references/checklists.md; the security-reviewer works from it at Gate 7.

• A valid token is not a resource check. Authentication says who is calling. It says nothing about whether that caller may touch this row. Every read, update, and delete keyed on a client-supplied ID needs an ownership or membership check on the server, in the same query that loads the row (WHERE id = ? AND owner_id = ?) rather than in a branch after it, so no code path can skip it. OWASP ranks broken object-level authorization #1 in the API Security Top 10 (API1:2023) and broken function-level authorization #5 — the same mistake at two granularities, so check admin and internal routes for a role, not just for a token. Non-guessable IDs (UUIDv4/v7) slow enumeration; they are not the control.
• Never bind a request body onto a persisted object. Allow-list the fields the client may set, per endpoint and per role. The ones that get you: role, is_admin, tenant_id, user_id, status, price, balance, verified, created_at. "Update the user from the body" is how a user promotes themselves. The response side is the same bug reversed — serialize an explicit field list, or password hashes, internal flags, and other users' columns ship to the client.
• Tenant isolation is per query, not per login. One missing WHERE tenant_id = ? is a cross-tenant breach, and it will be in the query somebody wrote by hand. Decide where the filter is enforced — a database row policy, a data-access layer nothing bypasses, or hand review on every query — and put that decision in the Assumption Ledger. Cache keys, rate-limit counters, search indexes, object-storage prefixes, background jobs, and exported files are queries too. Schema-level enforcement is mir-database.
• Client-side checks are hints, not controls. A hidden button, a disabled field, a role check in the UI, a validation rule in the form — all UX. The endpoint is callable directly. Re-validate every input and re-check every permission server-side on every request, including on endpoints only your own admin UI calls.
• Secrets and PII leak through logs and error responses, not only through breaches. Log the correlation ID, not the request body. Redact tokens, keys, card numbers, emails, and names at the logging boundary instead of trusting each call site. Return an opaque error plus an ID to the client; keep the stack trace, the SQL, and the upstream response server-side. Debug mode left on in production turns every 500 into an internal-state dump. PII you log inherits a different retention policy and a different access list than the table it came from.
• Injection is one bug in many places, but the control differs per interpreter. Never concatenate. SQL is the famous one — bind parameters. The same defect appears as NoSQL operator injection (a JSON body where a scalar was expected — coerce the type before it reaches the query), LDAP and XPath, server-side template injection, header/CRLF injection into a response or an outbound email, and log injection that forges audit lines. Shell is the one where "escape it" is the wrong answer: skip the shell and pass a fixed executable plus an argv array, then validate the operands — escaping a string still lets an attacker supply a leading - and inject an option the program honours. Identifiers — table, column, sort field — cannot be parameterized either; allow-list them.
• Insecure deserialization is remote code execution. Untrusted bytes never reach a native object deserializer (Java serialization, Python's stdlib object serializer, PHP unserialize, Ruby Marshal, unsafe YAML loaders). Use a data-only format, validate against a schema, and cap payload size and nesting depth. Cache entries, queue messages, and session cookies count as untrusted the moment an attacker can influence them.
• SSRF turns any user-supplied URL into your server's request from inside the network. Allow-list destination hosts. Validating the resolved IP is not enough on its own — the HTTP client then resolves the name again itself, and DNS can return a different answer the second time. Close that window: resolve, check every A/AAAA answer against private, loopback, link-local and reserved ranges, then connect to the validated IP with the Host header and SNI set to the original name. Disable redirect following and re-run the whole check per hop, or bound it. Set connect and read timeouts. The usual target is the cloud metadata endpoint, which hands out instance credentials — the provider-side controls for that are in mir-cloud. Webhook receivers, image fetchers, PDF renderers, and "import from URL" are all this.
• Verify what arrives, and bound it. Webhook signatures checked against the raw body, in constant time, before parsing. Rate limits and body-size limits on every public endpoint — unbounded resource consumption is a denial of service you also get billed for. Bound pagination and any client-controlled limit.

Everything upstream of the running process — dependency pinning, install scripts, CI secrets, image provenance, deploy IAM — is mir-devsecops, not this pillar.

Anti-Patterns (the failure this skill exists to prevent)

<anti_patterns>

</anti_patterns>

When to use a chain, not one pass

If the task spans multiple independent state-changing flows (e.g., orders and refunds and subscriptions), do not run one giant pipeline. Run Gate 0 once to map them, then one Gate 1–7 pass per flow. Tell the user explicitly: "This is three flows; I'll take them one at a time." A single mega-plan hides the places where two flows touch, and that is where the hardest bugs are.

Composing with your other skills

• anant-plan / GSD: this is the backend-specific planning layer. When a GSD/anant-plan phase is a backend feature, run this skill inside that phase's planning before writing the phase's code. It produces the Assumption Ledger + Risk Register that the phase plan should cite.
• Runtime tier + framework module (3-tier chain): this skill decides what's correct (any language); the runtime tier (mir-backend-python) carries what's true for all frameworks on that runtime (GIL, async/sync, fork-safety, cold start); the framework module (mir-backend-python-fastapi) knows the library's mechanics. At Gate 0 consult references/runtime-map.md to pick/validate the runtime; load the runtime tier + module at Gate 5/6.
• Sibling pillars — hand off, don't absorb. A task that spans two pillars gets two gate runs, not one merged pipeline.
• Schema, keys, constraints, indexes, tenancy layout, or a migration against populated tables → `mir-database`, and run it first: the invariants it puts in the database are the ones this pillar's code then defends. A CHECK constraint survives a buggy deploy; a service-layer if does not.
• Where the workload runs — provider, serverless vs container vs VM, region and data residency, egress cost, the IaC that pins the choice → `mir-cloud`. Gate 0 checks runtime fitness; it does not check infrastructure fitness.
• CI/CD workflows, dependency pinning and lockfiles, install scripts, secrets in the pipeline, image provenance, deploy IAM, release and rollback → `mir-devsecops`. Everything between the commit and the running process.
• The native app calling this API → `mir-mobile`; the browser client → `mir-frontend`. Idempotency has two halves — the client key there, the server-side dedup here. Run both.

Where these instructions live (edit map)

When you want to change or extend this kit, edit the right layer. Use the placement test:

Four questions pick the layer, in order:

"Is this about code running inside a request or a job in the application process?" If no, it belongs to a sibling pillar — schema to mir-database, infrastructure choice to mir-cloud, the delivery pipeline to mir-devsecops, the client to mir-frontend or mir-mobile.

"Is this true for Go and Node too?" → generic (edit mir-backend).

"Is it true for every framework on this runtime (FastAPI + Django + Flask)?" → runtime tier (edit mir-backend-python) — e.g. the GIL, async/sync, fork-safety, cold start.

"Does it only bite in this one library (FastAPI / SQLAlchemy / Alembic / Redis)?" → framework module (edit mir-backend-python-fastapi).

New runtime (Node, Go, JVM…)? → new mir-backend-<runtime> tier. New framework on an existing runtime? → new mir-backend-<runtime>-<framework> module. Copy the nearest sibling's shape; never widen a higher tier.

Rule of thumb for this skill's own references (the generic core):

• references/constraint-catalog.md — the full question bank by dimension (Domain/Data/Scale/Failure/Security/Operations) + invariant patterns. Read by the interrogator at Gate 1.
• references/failure-mode-catalog.md — the 15 pitfalls expanded. Read at Gate 3/4.
• references/checklists.md — codegen checklist (Gate 6) + production-readiness checklist (Gate 7), including the full Security list the security-reviewer works from. Read by the reviewers at Gate 7.
• references/runtime-map.md — runtime/workload fitness table (your stack vs "when NOT to use it"), the dated version floors, and which runtime tier/module to load. Read at Gate 0.

Provenance

Distilled from a constraint-discovery analysis of where AI backend code fails (the "AI is weak at assumption discovery, not code synthesis" reframe) and the user's Prompt Architect protocol (restate intent → surface unknowns → ask 2-4 Qs with a recommended default → think about failure before building → negative + positive constraints → chain when needed → end with a test guide). The gate-and-sub-agent structure mirrors the 2026 pattern: Planner → Architect → Implementer → Reliability Reviewer → Security Reviewer, replacing one-shot "prompt → giant code dump."