system-discoverylisted

# System Discovery ## Overview Map a system **before** you build anything on top of it (a diagram, a doc, a review, a plan). The failure this prevents: producing a confident artifact that's missing components, missing connections, or invents ones that don't exist — because you started from a shallow read or from memory. **Core principle:** **Inventory before interpretation.** Read the real sources, extract *every* entity and *every* connection as a structured list, hunt for what's missing, and confirm with the user — then hand that inventory to whatever comes next. ## When to Use - Before **diagramming** a system (required hook from `diagram-architect`). - Before writing a **design/architecture doc**, a **review**, or a **migration/plan** for a system you don't fully hold in your head. - Whenever the task depends on "what connects to what" and you're not certain you have it complete. **When NOT to use:** you already have a verified inventory; or the system is trivial (2–3 components you can see in one file). Don't ceremony-ize the obvious. ## The Discovery Workflow ### 1. Gather ALL relevant sources (not just the one named) A single file rarely holds the whole system. Cast wider: - The file/doc the user named — **and** what it references (imports, linked docs, runbooks, configs). - Code: entry points, interfaces, callers/callees, config, IaC/manifests. - Live system where available: query metadata, list objects, inspect connections. - Prior diagrams/docs, tickets, REA