System Map

Build a working model of a system, its stocks, flows, and the dependencies insiders cannot see, with a Mermaid diagram and the constraint that governs throughput. Enter a system and optional objective, scope, stakeholders, context, or focus areas. Now with non-obvious dependency mining, failure traces, and declared map-unreliability regions.

Also available as a skill: System Map agent skill

# System Map

You are building a system map: a structural model of how a system actually works — its components, flows, and dependencies — accurate enough to reason against. The deliverable is **not** a labeled inventory — it is a **working model**: the map plus the non-obvious dependencies it exposes, the constraint that governs throughput, and an honest account of where the map itself is unreliable. Everything else in the process exists to get you there.

## Input

- **System** (required): the workflow, organization, pipeline, or structure to map.
- **Objective** (optional): what the map is for — optimization, onboarding, risk, redesign. Default: find the governing constraint.
- **Scope** (optional): boundaries to respect or include.
- **Stakeholders / Context / Focus areas** (optional): shape emphasis and step 6 (grounding); must never narrow what the map is allowed to notice.

## Process

Run all six steps. Steps 1–2 are setup — keep them brutally short. Steps 3–5 are the work.

### 1. Declare the boundary and the map's purpose (≤3 sentences)
What's inside, what's environment, and what question this map must be able to answer. A map with no question answers none. Note the strongest case for a different boundary in one clause — boundary choices hide dependencies by construction.

### 2. Separate stocks from flows (≤6 lines)
Name the system's **stocks** (where things accumulate and wait: queues, inventories, balances, backlogs, knowledge held by one person) and its **flows** (what moves between them, at roughly what rate). **Known bias (hypothesized): system maps come out as org charts — boxes for who, arrows for reports-to — because component lists are easy to generate. Behavior doesn't live in the boxes; it lives in the stocks and the rates, and a map without them can't answer "why is it slow" or "what breaks first."**

### 3. Map the structure — diagram plus narration
Produce a **Mermaid diagram** (flowchart or graph as fits) of components, stocks, and flows — compact enough to read, honest about what was left out. Then narrate only what the diagram can't carry:

- **Flow rates and capacities** where they're known or estimable — an arrow without a rate is a rumor.
- **The informal paths:** the workaround, the shadow spreadsheet, the person everyone actually asks. Every mature system has at least one path that doesn't appear in its official description; if you found none, the map is reproducing the system's self-image. Say which paths are official and which are observed/inferred.
- **Coupling notes:** which connections are tight (failure propagates immediately) vs. loose (buffered, deferrable).

### 4. Surface the non-obvious dependencies — the centerpiece
The map must expose **at least one dependency that a competent insider would not have drawn** — a shared resource two "independent" processes both drain, a feedback path from output back to input, a single point of failure hiding behind apparent redundancy, a timing coupling (two processes that only work because of an accidental schedule alignment). For each:

- **The mechanism:** how the dependency transmits — what moves along it, how fast, triggered by what.
- **The insider test (mandatory):** would someone operating this system daily already know this? If every dependency on the map passes through common knowledge, the map is a re-description, not a model — dig again, especially in the informal paths and the stocks (hidden dependencies pool where things wait).
- **The failure trace:** walk one concrete failure through the dependency — what breaks, what it takes down, how long until it's visible.

### 5. Find the governing constraint
Identify the **one stock or flow that currently governs system throughput** — the bottleneck everything else queues behind. Test it: if this constraint were relaxed, what's the *next* constraint, and how much headroom before it binds? (A constraint with no successor identified hasn't been verified — relaxing it may just be feeding the real one.) Then state **where this map is wrong**: the region you have least evidence for, the simplification most likely to mislead, the part of the system that changes too fast for the map to hold. A map that doesn't declare its unreliable regions gets trusted uniformly, which is worse than not being trusted at all.

### 6. Ground it (brief)
Two or three implications calibrated to the objective: the intervention the constraint analysis points to, the measurement that would firm up the map's weakest region, the dependency most worth instrumenting before it surprises someone. If the objective was optimization and the honest finding is "the constraint is outside the declared scope," say that plainly — it's a boundary finding, not a failure.

## Discipline (applies throughout)

- **Banned without specifics:** "complex," "siloed," "lack of visibility," "single source of truth," "streamline." If a property is real, name the stock, flow, or dependency that carries it.
- **Prefer one surprising dependency over total coverage.** A map that's 60% complete but exposes the timing coupling nobody knew about beats an exhaustive diagram of the already-known.
- **The diagram serves the findings, not the reverse.** If the diagram is getting dense, cut passenger components and say what you cut — the map's job is to make the dependencies and constraint legible, not to be complete.
- **No hedging-as-rigor.** Commit to the constraint diagnosis, then declare the map's unreliable regions — that is the honest form of uncertainty.

## Output shape

No fixed template. Required artifacts, in order: boundary + purpose line → stocks and flows → **diagram with narration** → **non-obvious dependencies** (the bulk) → governing constraint + where-the-map-is-wrong → grounding. Do not append a summary that restates the findings — end on the grounding. Deliver final text only: no visible self-correction or editorial asides.