explain-system-tradeoffs

What this skill does

# Explain System Tradeoffs

Reverse-engineer distributed system tradeoffs from code, configuration, deployment
manifests, and architecture artifacts. Produce an evidence-based report that explains
what the system prioritizes, what it sacrifices, where choices appear deliberate versus
accidental, and what risks or misalignments deserve attention.

Every distributed system encodes its design tradeoffs in artifacts hiding in plain
sight — configuration files, schema definitions, deployment manifests, timeout values,
retry policies, and code patterns. This skill reads those artifacts like an
architectural blueprint.

## Evidence Tiers

When evaluating evidence, use three tiers to weigh confidence:

- **Tier A (hard commitments):** User-facing API/SLA language; explicit consistency or
  transaction guarantees; quorum/replication rules; schema invariants; wire-protocol
  requirements.
- **Tier B (mechanism evidence):** Concrete mechanisms that enforce the property —
  consensus protocols, leases, retry state machines, outbox tables, circuit breaker
  configs, compaction strategies, GC flags.
- **Tier C (operational signatures):** Dashboards, alerts, runbooks, incident
  postmortems, sampling configs, SLO definitions that reveal what engineers actually
  protect and what they sacrifice.

When indicators disagree, prefer artifacts closest to runtime behaviour (Tier C and B)
over architecture documentation that may be stale (Tier A language in old design docs).

## Subcommands

Request a full analysis or focus on a single tradeoff axis:

| Command Pattern | Axis | Reference |
|----------------|------|-----------|
| `explain-system-tradeoffs` | All six axes | All references |
| `explain-system-consistency-tradeoffs` | Consistency & Availability | `references/consistency.md` |
| `explain-system-latency-tradeoffs` | Latency & Throughput | `references/latency.md` |
| `explain-system-data-tradeoffs` | Data Distribution | `references/data-distribution.md` |
| `explain-system-transaction-tradeoffs` | Transaction Boundaries & Coordination | `references/transactions.md` |
| `explain-system-resilience-tradeoffs` | Resilience & Failure Isolation | `references/resilience.md` |
| `explain-system-operations-tradeoffs` | Observability, Security & Cost | `references/operations.md` |

When no subcommand is specified, default to analyzing all six axes.
When a tradeoff axis is mentioned by name or concept (even without the command prefix),
match it to the appropriate subcommand.

## Workflow

### Single-Axis Mode

When a single axis is requested (e.g., `explain-system-consistency-tradeoffs`),
execute the analysis directly in the main agent:

1. **Identify the target** code, configuration, or architecture to analyze.
2. **Read the reference file** for the requested axis.
3. **Scan the codebase** for indicators described in the reference.
4. **Build an evidence ledger** and report findings (see Report Format below).

### Full Analysis Mode (Parallel Subagents)

When all six axes are requested (`explain-system-tradeoffs`), use **parallel
subagents** to analyze each axis concurrently. This is faster and produces
better results because each subagent can focus deeply on one axis.

**CRITICAL — How parallel execution works:** The Task tool runs subagents in
parallel ONLY when multiple Task tool calls appear in the SAME response message.
If you emit them across separate messages, they run sequentially. You MUST
include all six Task tool calls in a single response to get concurrency.

#### Step 1. Identify Target System

Determine what code, configuration, or architecture to analyze:
- When files or a directory are provided, use those.
- When a service, module, or system is referenced by name, locate it.
- When ambiguous, ask which files, directories, or services to scan.

Resolve the target to a concrete set of paths before launching subagents.
This MUST be done before Step 2 — subagents get their own isolated context
window and cannot see the conversation history or resolve ambiguous targets.

#### Step 2. Launch Six Parallel Subagents

Emit **exactly six Task tool calls in a single response message**. This is
what triggers concurrent execution. Do NOT emit them one at a time.

Technical requirements for each Task call:
- `subagent_type`: `"general-purpose"`
- `description`: Short label (e.g., `"Analyze consistency tradeoffs"`)
- `prompt`: A **fully self-contained** prompt (see template below). Each
  subagent gets its own 200k context window and cannot see the main
  conversation, so the prompt must include everything it needs.

Each subagent prompt must include:
1. The **concrete target paths** to analyze (resolved in Step 1).
2. The **absolute path to its reference file** to read first.
3. The **evidence tier definitions** (Tier A/B/C — copy them into the prompt).
4. The **per-axis report format** (copy it into the prompt).
5. An instruction to **return structured findings only** — no summary, no
   cross-axis commentary (the main agent handles synthesis).

The six subagents and their reference files:

| Subagent | Reference to read | Focus |
|----------|------------------|-------|
| Consistency & Availability | `references/consistency.md` | CAP/PACELC position, replication, quorum, cache freshness, conflict resolution |
| Latency & Throughput | `references/latency.md` | GC tuning, thread pools, batching, deadlines, hedging, storage engines, rate limiting |
| Data Distribution | `references/data-distribution.md` | Shard keys, partition strategies, replication topology, data sovereignty |
| Transaction Boundaries | `references/transactions.md` | Monolith vs microservices, sagas, outbox, schema evolution, API contracts, dependencies |
| Resilience & Failure Isolation | `references/resilience.md` | Circuit breakers, retries, bulkheads, chaos engineering, progressive delivery, service mesh |
| Observability, Security & Cost | `references/operations.md` | Tracing, SLOs, mTLS, audit trails, compliance, cost/reliability topology |

**Subagent prompt template** (adapt the axis name, reference path, and focus
for each of the six — but keep the structure identical):

```
Analyze the distributed system tradeoffs for the CONSISTENCY & AVAILABILITY axis
in the codebase at: <TARGET_PATHS>

STEP 1: Read the reference file at:
<ABSOLUTE_PATH_TO_SKILL_DIR>/references/consistency.md

STEP 2: Scan the target codebase for indicators described in the reference.
Search configuration files, code patterns, deployment manifests, and schema
definitions. Use Glob, Grep, and Read tools to find evidence.

STEP 3: For each piece of evidence found, classify it:
- What: The specific artifact (file path, config key, code pattern)
- Tier: A (hard commitment — SLA language, quorum rules, schema invariants),
        B (mechanism evidence — protocols, configs, GC flags, compaction),
        or C (operational signature — dashboards, alerts, SLOs, runbooks)
- Reveals: Which end of the tradeoff spectrum the system leans toward
- Deliberate vs Default: Whether intentional (asymmetric config, tuned values)
  or accidental (framework defaults, copy-pasted settings)

STEP 4: Produce your findings in EXACTLY this format:

## Consistency & Availability

**Position:** [Where the system sits on the consistency/availability spectrum]
**Confidence:** HIGH | MEDIUM | LOW

### Evidence
[Numbered list of evidence items with Tier, File, and Detail for each]

### Assessment
[1-2 paragraphs on the tradeoff position and whether it appears deliberate]

### Risks & Recommendations
[Any risks found, each with: Severity (HIGH/MEDIUM/LOW), Location, Issue,
Recommendation. If no risks found, state "No significant risks identified."]

IMPORTANT: Return ONLY the per-axis report above. Do NOT produce a cross-axis
summary or tradeoff profile — the main agent handles cross-axis synthesis.
```

#### Step 3. Wait for All Subagents

**CRITICAL — Do NOT continue analysis while subagents are running.** After
launching the six subagents, your ONLY job