Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    System Design Compass

    1

    A disciplined AI agent skill for production architecture reviews, narrow ADRs, and safe migrations. Identifies critical invariants and stress-tests designs against failure paths.

    Free

    Security scanned
    System Design Compass

    System Design Compass

    Example session with this skill installed

    Review our payment wallet settlement flow. We have an API gateway calling a third-party payment processor, then writing balance updates to Postgres. We are seeing duplicate charge risks during gateway timeouts. Focus on retry identity, atomic ledger updates, and external provider ambiguity.

    • Read your context and instructions
    • Compiled the system design compass

    I reviewed the payment wallet settlement flow. The primary risk is duplicate debits caused by ambiguous remote timeouts: when the third-party processor succeeds but the network times out before returning a response, naive retries re-execute the charge under a new request context.

    Architectural Assessment: Payment Wallet Settlement

    BoundaryInvariantFailure ModeEnforcement Mechanism
    Retry IdentityExactly-once financial effect per client operationClient retries after network drop; generates fresh requestScope idempotency key by tenant_id:account_id:idempotency_key at the API boundary before calling external services.
    Provider AmbiguityNo local ledger commit without verified external state30s timeout on payment capture; outcome unknownStore payment intent as PENDING with deterministic key; query provider reconciliation API before retry or refund.
    Ledger AtomicityBalance debit and transaction record commit togetherDB connection drops after balance deductionWrap balance decrement and audit ledger entry in a single serializable database transaction.
    Rollback SafetyIrreversible external charges cannot be rolled back locallyFailed ledger write leaves external capture orphanBackground reconciliation worker polls pending intents, resolves final status, and issues refunds if unlinked.

    Concrete Violating Failure Sequence

    1. Client submits $50 wallet transfer with idempotency_key: tx_981.
    2. Gateway stores intent tx_981 as PENDING and calls Payment Processor.
    3. Payment Processor captures $50 successfully, but response drops due to a transit timeout.
    4. Client SDK times out after 10s and retries the request with a newly generated UUID tx_982.
    5. Gateway treats tx_982 as a new transaction and captures another $50, causing a double debit.

    Smallest Defensible Correction

    Contract-Scoped Idempotency: Require the client to retain the original business transaction identity across retries. Reject attempts to reuse keys across different payloads.
    2.

    Intent Reservation: Commit an INTENT record with status PROCESSING in Postgres prior to dispatching external network calls.
    3.

    Reconciliation Gate: When a remote call times out, do not fail or retry immediately. Transition intent to IN_DOUBT and invoke the provider's GET /v1/charges/{idempotency_key} status endpoint before deciding whether to retry or reverse.

    Validation Test and Observable Oracle

    • Fault Schedule: Inject a 15-second dropped connection on the processor HTTP response socket during test runs.

    Pass/Fail Oracle: After 5 retry attempts by the client, total external settled volume must equal exactly $50 (1 charge), local ledger must reflect exactly one debit, and zero orphan pending intents remain after the reconciliation worker executes.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    Architecture decisions often stall on superficial trade-offs or unverified assumptions. Generic advice tells teams to "use a queue" or "add idempotency", but skips the operational failure modes that break production systems.

    System Design Compass gives your coding agent a structured framework to audit architectures, write defensible Architectural Decision Records (ADRs), and evaluate complex migrations. Instead of generic summaries, it forces your agent to identify authoritative state owners, construct concrete violating failure sequences, and specify testable validation oracles.

    What the skill does

    • Direct ADR Decisions: Produces concise, scoped decisions covering latency, isolation boundaries, retry safety, cost drivers, and measurable reconsideration triggers.
    • Deep Architecture Reviews: Audits proposed or existing systems against repository facts. Cites exact code evidence, measures blast radius, and recommends the smallest viable correction.
    • Zero-Downtime Migration Planning: Plans safe database and service migrations. Defines per-phase sources of truth, dual-write convergence gates, cutover barriers, and rollback contracts.
    • Production Readiness Audits: Evaluates queue backlog recovery capacity, lease fencing mechanisms, replication lag, and disaster recovery boundaries.
    • System Design Practice: Facilitates structured mock architecture interviews with time-boxed scoping, capacity estimation, and rubric-driven feedback.

    How it works

    The skill uses selective on-demand routing. Instead of loading thousands of tokens on every conversation turn, a compact 397-word entrypoint (SKILL.md) routes requests by the unresolved decision:

    • Narrow decisions: Resolved directly within the entrypoint.
    • Complex workflows: Selectively loads only the relevant boundary reference among 14 focused guides or 28 production workload archetypes.
    • Zero runtime dependencies: Requires no external MCP servers, runtime scripts, or API keys. Follows the open Agent Skills specification.

    Three engineering reminders built into every review

    1. A timeout is an unknown outcome: Never treat an ambiguous remote call as a clean failure before resolving external state.
    2. Queue storage is not recovery capacity: Backlog clearance requires net positive completion headroom above normal arrivals plus retries.
    3. Restoring old binaries does not undo incompatible writes: Rollback safety depends on mixed-version read and write compatibility.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 18 days ago

    • Free with an Agensi account

    Permissions

    Read Files
    Terminal / Shell
    Write Files
    Listed18 days ago

    What's inside

    Frequently Asked Questions

    A: No. System Design Compass is built entirely with pure Markdown guides. It has zero runtime dependencies, makes no external network calls, and requires no third-party API credentials.

    The skill follows the open Agent Skills specification (agentskills.io). It works across Claude Code, Cursor, Codex CLI, Gemini CLI, VS Code Copilot, and any environment that discovers SKILL.md.

    The repository includes a blind comparative evaluation suite (evals/). On the 1.1.0 candidate entrypoint, all 8/8 core benchmark cases passed under tool-free blind grading on Gemini 3.8 Flash Medium with zero critical violations.

    While it doesn't require a complex installation, you will need to provide specific workload inputs like SLOs and demand units to get the most accurate capacity and stress-test results.

    Yes, the skill is highly effective for high-stakes scenarios like zero-downtime database migrations, as it maps out restart/repair logic and manages mixed-version read/write risks.

    This skill focuses on the architectural decision-making and logic layer; it does not perform routine code implementation until the underlying architectural invariants are finalized.

    New in APIs & Backend