Overview
Perspective shift. The user is staring at a function, file, or module and cannot see the system around it. This skill widens the lens until the role of the code is clear, then stops.
When to Use
- The user says "zoom out", "what is this", "where does this fit", "give me context on this code", or "what calls this".
- The user names one file or one line and cannot say which module owns it or who calls it.
For line-by-line review, use /review; for a bug hunt, use /investigate; for whole-repository orientation, use /onboard.
Arguments
<path> or <path>:<line>: the file or location to zoom out from. Required.--depth <n>: how many hops outward to trace. Default 2, max 4. Higher depth burns context fast.
Process
1. Read the target
Read the full file at <path>. If a line number is given, read 30 lines around it. Identify:
- The primary export or symbol at the location.
- Other exports in the same file.
- Imports from inside the project versus from third-party packages.
2. Trace inward (callees)
For each function the target calls, locate its definition. Note:
- Which module it lives in.
- Whether it is pure or has side effects such as I/O, network, database, or global state.
- Whether it is project code or library code.
Stop at depth 1 unless --depth is higher.
3. Trace outward (callers)
Grep the project for usages of the target's exports. For each caller:
- Which module imports it.
- The shape of the call site, one-shot, loop, retry, conditional.
- Whether the caller is a route handler, a job, a CLI entry, a test, or another internal module.
4. Identify the module boundary
Group the files touched in steps 2 and 3 by directory and by responsibility. State:
- Which module the target belongs to.
- Which neighboring modules it talks to.
- Whether the boundary looks intentional or accidental such as cross-cutting imports, circular references, or leaky abstractions.
5. Name the architectural role
Pick the closest match from this list. Add a one-line justification.
| Role |
Signal |
| Domain logic |
Pure functions, no I/O, expresses business rules |
| Application service |
Orchestrates domain calls and infrastructure, no business rules |
| Adapter |
Translates between an external system and the domain |
| Controller / route handler |
Sits at the HTTP, queue, or CLI boundary |
| Repository |
Persists or retrieves domain objects |
| Utility |
Stateless helper used across modules |
| Configuration |
Loads, validates, or exposes config |
| Entry point |
Wires the system at startup |
If the target spans more than one role, that is itself a finding. Surface it.
6. Surface hidden coupling
List anything that would surprise a new contributor:
- Side effects at module load time. See the "No side effects at module level" bullet under "Fundamentals" in
standards/code-style.md.
- Shared mutable state.
- Implicit ordering requirements between callers.
- Logic that depends on environment variables read deep in the call stack.
- Type assertions that hide a contract violation.
7. Output
Produce a single report. No file edits. Format:
# Zoom-out: <path>
## What it is
One paragraph. Primary purpose, surface area, dependencies.
## Role
<role from the table>. Justification: <one line>.
## Callers (depth N)
- file:line - <one line>
- file:line - <one line>
## Callees (depth N)
- file:line - <one line>
- file:line - <one line>
## Module boundary
- Lives in: <module>
- Talks to: <neighbor modules>
- Boundary health: clean / leaky / circular / cross-cutting
## Hidden coupling
- <finding> at file:line
- <finding> at file:line
## Suggested next reads
- file:line - reason
- file:line - reason
Rules
- This skill never edits code. It produces a report only.
- Cap depth at 4. Beyond that, the report stops being a zoom-out and becomes a survey.
- Cite every claim with
file:line. No abstract statements about "the architecture".
- If the role does not match the table, say so explicitly. Do not invent a category.
- Stop after the report. Do not propose refactors. Use
/refactor for that.
Common Rationalizations
- "The file name says what it does": a name is a claim. The callers in step 3 show the role the code actually plays.
- "Depth 4 gives a fuller picture": past depth 4 the report turns into a survey, and the role of the target gets lost in it.
- "It is close enough to Application service": a near match hides the finding. Say the role does not fit the table and describe what it does.
- "The coupling is obvious, no need to cite it": every hidden-coupling item carries a
file:line so the reader can check it in one step.
Red Flags
- Stop and run the caller grep when the Callers list is empty and the target has exports.
- Stop and cite the location when a claim in the report carries no
file:line.
- Stop at the report when the next step you are drafting is an edit or a refactor proposal.
- Stop and narrow
--depth when the traced file count passes what fits in one report.
Verification
- The report has every heading from the step 7 template.
- Every caller, callee, and hidden-coupling line cites
file:line.
- The role names one table entry with a justification, or says plainly that none fits.
- No file was modified during the run.
Related skills
/onboard for whole-repo orientation./explain for line-level explanation of a block./refactor after the zoom-out reveals a structural problem./investigate when the goal is finding a bug, not understanding the structure.
1---2name: zoom-out3description: Step back from a narrow code section and place it in its system context. Reads the file, traces callers and callees, identifies the module boundary, names the architectural role, and surfaces hidden coupling. Use when user says "zoom out", "what is this", "where does this fit", "give me context on this code", "what calls this", or feels lost in unfamiliar code. For line-by-line code review, use /review; for debugging, use /investigate; for onboarding to a whole repo, use /onboard.4allowed-tools:5 - Read6 - Glob7 - Grep8argument-hint: "/zoom-out src/billing/invoice.ts:42 [--depth 3]"9metadata:10 source: https://skillmd.com/skills/gufranco/zoom-out11---1213## Overview1415Perspective shift. The user is staring at a function, file, or module and cannot see the system around it. This skill widens the lens until the role of the code is clear, then stops.1617## When to Use1819- The user says "zoom out", "what is this", "where does this fit", "give me context on this code", or "what calls this".20- The user names one file or one line and cannot say which module owns it or who calls it.2122For line-by-line review, use `/review`; for a bug hunt, use `/investigate`; for whole-repository orientation, use `/onboard`.2324## Arguments2526- `<path>` or `<path>:<line>`: the file or location to zoom out from. Required.27- `--depth <n>`: how many hops outward to trace. Default 2, max 4. Higher depth burns context fast.2829## Process3031### 1. Read the target3233Read the full file at `<path>`. If a line number is given, read 30 lines around it. Identify:34- The primary export or symbol at the location.35- Other exports in the same file.36- Imports from inside the project versus from third-party packages.3738### 2. Trace inward (callees)3940For each function the target calls, locate its definition. Note:41- Which module it lives in.42- Whether it is pure or has side effects such as I/O, network, database, or global state.43- Whether it is project code or library code.4445Stop at depth 1 unless `--depth` is higher.4647### 3. Trace outward (callers)4849Grep the project for usages of the target's exports. For each caller:50- Which module imports it.51- The shape of the call site, one-shot, loop, retry, conditional.52- Whether the caller is a route handler, a job, a CLI entry, a test, or another internal module.5354### 4. Identify the module boundary5556Group the files touched in steps 2 and 3 by directory and by responsibility. State:57- Which module the target belongs to.58- Which neighboring modules it talks to.59- Whether the boundary looks intentional or accidental such as cross-cutting imports, circular references, or leaky abstractions.6061### 5. Name the architectural role6263Pick the closest match from this list. Add a one-line justification.6465| Role | Signal |66|------|--------|67| Domain logic | Pure functions, no I/O, expresses business rules |68| Application service | Orchestrates domain calls and infrastructure, no business rules |69| Adapter | Translates between an external system and the domain |70| Controller / route handler | Sits at the HTTP, queue, or CLI boundary |71| Repository | Persists or retrieves domain objects |72| Utility | Stateless helper used across modules |73| Configuration | Loads, validates, or exposes config |74| Entry point | Wires the system at startup |7576If the target spans more than one role, that is itself a finding. Surface it.7778### 6. Surface hidden coupling7980List anything that would surprise a new contributor:81- Side effects at module load time. See the "No side effects at module level" bullet under "Fundamentals" in [`standards/code-style.md`](../../standards/code-style.md).82- Shared mutable state.83- Implicit ordering requirements between callers.84- Logic that depends on environment variables read deep in the call stack.85- Type assertions that hide a contract violation.8687### 7. Output8889Produce a single report. No file edits. Format:9091```markdown92# Zoom-out: <path>9394## What it is95One paragraph. Primary purpose, surface area, dependencies.9697## Role98<role from the table>. Justification: <one line>.99100## Callers (depth N)101- file:line - <one line>102- file:line - <one line>103104## Callees (depth N)105- file:line - <one line>106- file:line - <one line>107108## Module boundary109- Lives in: <module>110- Talks to: <neighbor modules>111- Boundary health: clean / leaky / circular / cross-cutting112113## Hidden coupling114- <finding> at file:line115- <finding> at file:line116117## Suggested next reads118- file:line - reason119- file:line - reason120```121122## Rules123124- This skill never edits code. It produces a report only.125- Cap depth at 4. Beyond that, the report stops being a zoom-out and becomes a survey.126- Cite every claim with `file:line`. No abstract statements about "the architecture".127- If the role does not match the table, say so explicitly. Do not invent a category.128- Stop after the report. Do not propose refactors. Use `/refactor` for that.129130## Common Rationalizations131132- "The file name says what it does": a name is a claim. The callers in step 3 show the role the code actually plays.133- "Depth 4 gives a fuller picture": past depth 4 the report turns into a survey, and the role of the target gets lost in it.134- "It is close enough to Application service": a near match hides the finding. Say the role does not fit the table and describe what it does.135- "The coupling is obvious, no need to cite it": every hidden-coupling item carries a `file:line` so the reader can check it in one step.136137## Red Flags138139- Stop and run the caller grep when the Callers list is empty and the target has exports.140- Stop and cite the location when a claim in the report carries no `file:line`.141- Stop at the report when the next step you are drafting is an edit or a refactor proposal.142- Stop and narrow `--depth` when the traced file count passes what fits in one report.143144## Verification145146- The report has every heading from the step 7 template.147- Every caller, callee, and hidden-coupling line cites `file:line`.148- The role names one table entry with a justification, or says plainly that none fits.149- No file was modified during the run.150151## Related skills152153- `/onboard` for whole-repo orientation.154- `/explain` for line-level explanation of a block.155- `/refactor` after the zoom-out reveals a structural problem.156- `/investigate` when the goal is finding a bug, not understanding the structure.
