- Home
- Skills
- APIs & Backend
- System Design Compass
Works with the AI Agents you already use
System Design Compass
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
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
| Boundary | Invariant | Failure Mode | Enforcement Mechanism |
|---|---|---|---|
| Retry Identity | Exactly-once financial effect per client operation | Client retries after network drop; generates fresh request | Scope idempotency key by tenant_id:account_id:idempotency_key at the API boundary before calling external services. |
| Provider Ambiguity | No local ledger commit without verified external state | 30s timeout on payment capture; outcome unknown | Store payment intent as PENDING with deterministic key; query provider reconciliation API before retry or refund. |
| Ledger Atomicity | Balance debit and transaction record commit together | DB connection drops after balance deduction | Wrap balance decrement and audit ledger entry in a single serializable database transaction. |
| Rollback Safety | Irreversible external charges cannot be rolled back locally | Failed ledger write leaves external capture orphan | Background reconciliation worker polls pending intents, resolves final status, and issues refunds if unlinked. |
Concrete Violating Failure Sequence
- Client submits $50 wallet transfer with
idempotency_key: tx_981. - Gateway stores intent
tx_981asPENDINGand calls Payment Processor. - Payment Processor captures $50 successfully, but response drops due to a transit timeout.
- Client SDK times out after 10s and retries the request with a newly generated UUID
tx_982. - Gateway treats
tx_982as 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
- A timeout is an unknown outcome: Never treat an ambiguous remote call as a clean failure before resolving external state.
- Queue storage is not recovery capacity: Backlog clearance requires net positive completion headroom above normal arrivals plus retries.
- Restoring old binaries does not undo incompatible writes: Rollback safety depends on mixed-version read and write compatibility.
How to use
- 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
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 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