zoom-out

# Zoom Out

## One-Liner

When lost in code detail, go up a layer of abstraction — map all relevant modules and callers using the project's own vocabulary before touching anything.

---

## § 1 · Core Philosophy

Implementation details are the lowest layer of knowledge. When you are lost in them, the fastest path forward is not to read more code at the same level — it is to **ascend** until you can see the module boundaries, the data flow, and the domain terms the project actually uses.

A zoom-out produces a **map**, not a reading. The map tells you:
- What modules own what behavior
- Where the seams are (where behavior can shift without editing in place)
- What the project calls things (canonical vocabulary that later prompts should reuse)

---

## § 2 · Workflow

### Step 1 — Read Domain Context First

Before exploring code, look for existing orientation documents:

1. `CONTEXT.md` — domain glossary and canonical terms
2. `README.md` or `docs/` — high-level architecture
3. ADR files (`docs/adr/`, `decisions/`) — past architectural decisions
4. `AGENTS.md` or `SKILL.md` — any agent-specific context

If these exist, read them **before** opening source files. They compress hours of reading into minutes.

### Step 2 — Identify the Entry Point

For the area you need to understand, find the highest-level caller:

- For a web request: the router or controller
- For a CLI: the top-level command handler
- For a library: the public API surface (`index.ts`, `__init__.py`, `lib.rs`)
- For a background job: the scheduler or queue consumer

### Step 3 — Map One Layer at a Time

Starting from the entry point, map **one call level at a time**:

```
Entry point
  └── Module A  (owns: X, Y)
        └── Module B  (owns: Z)
              └── Module C  (owns: persistence)
  └── Module D  (owns: validation)
```

For each module, note:
- What it **owns** (single responsibility)
- What it **calls** (dependencies)
- What it **exposes** (public interface)

Stop when you reach the level relevant to your task — you do not need to map the entire codebase.

### Step 4 — Collect Domain Vocabulary

As you map, note every domain-specific term you encounter:
- Entity names (Order, Account, Shipment)
- Action names (fulfill, provision, reconcile)
- State names (pending, in-flight, settled)

These are the **canonical terms** you must use in all subsequent prompts and code. Using non-canonical terms causes agents to introduce inconsistencies.

### Step 5 — Produce the Map

Output a structured summary:

```
## Module Map: <area>

Entry: <file or function>
Domain terms: <list>

Modules:
- <name>: owns [X, Y] | calls [A, B] | public interface: <description>
- ...

Key seams (where behavior can be changed without editing in place):
- <description>

Open questions:
- <anything that needs clarification before editing>
```

---

## § 3 · Signs You Need This Skill

- "I'm not sure which file owns this behavior"
- "I keep finding circular dependencies when I try to trace the flow"
- "The agent keeps using the wrong terminology"
- "I want to refactor but I don't know where the seams are"
- "I need to add a feature but I don't know which module it belongs in"

---

## § 4 · When to Use This Skill

**Use when:**
- Starting work in an unfamiliar part of the codebase
- Before any significant refactor
- Before designing a new feature that touches existing modules
- When an agent has been producing inconsistent terminology

**Do NOT use when:**
- The area is already well-understood (skip the overhead)
- The codebase is small enough to hold entirely in context

---

## § 5 · Relationship to Other Skills

| Skill | When to reach for it |
|-------|---------------------|
| `tdd-workflow` | After zoom-out — you know the interfaces, start writing tests |
| `debug-diagnose` | After zoom-out — you have the map to place your feedback loop |
| `architecture-review` | After zoom-out reveals shallow modules or unclear ownership |
| `grill-with-docs` | After zoom-out — validate your understanding against domain docs |