---
name: apt:zoom-out
description: "Orient yourself in an unfamiliar area of the codebase — load CONTEXT.md, map modules + callers, output a one-page orientation"
apt-skill-version: {{APT_VERSION}}
stage: plan
intent: investigate
when_to_use: "The user is dropped into a part of the codebase they don't know and wants a one-page architectural orientation before planning or editing. Natural-language triggers: 'give me a broader picture of X', 'I'm lost in this area', 'explain how this fits'."
user_invocable: true
internal: false
spawns_agent: false
agent_name: null
task_context: none
default_track: STANDARD
default_execution_mode: auto
execution_modes:
  - auto
  - step
allowed-tools: "Bash, Read, Grep, Glob"
argument-hint: "apt:zoom-out [area-name]"
gates: []
---

# Zoom-Out — One-page Architectural Orientation

Tiny skill. High signal. The user named an area; you produce a one-page
orientation so they (or a future agent) can plan or edit without
re-learning the codebase from scratch.

**Aperant adoption note.** This skill descends from 's `zoom-out`
discipline. Aperant's router is dynamic and LLM-driven, so unlike 's
upstream this skill is **router-invocable** (no `disable-model-invocation:
true` flag). The work-intent — "give me a broader picture of X" — is
genuine and the router resolves natural-language triggers without forcing
the user to remember the verb name.

## When to Use

- Dropped into a new module / package / area of the monorepo
- About to plan a feature that crosses an unfamiliar boundary
- The codebase has CONTEXT.md (Aperant glossary) and you want to load it
  alongside the structural map

## When Not to Use

- The area is one you know well — `/apt:plan` already does targeted
  investigation
- You need to lock decisions (use `/apt:discuss` with the
  `appendices/grill-discipline.md` posture loader instead)
- The user wants to refactor proactively — that's `/apt:improve`

## Process

### 1. Parse the area name

Extract the area from `$ARGUMENTS`. The area is a noun phrase, not a
file path: e.g., `"chat session lifecycle"`, `"sparring engine"`,
`"feature registry"`. If the argument is a file path, narrow the
orientation to the file's enclosing module.

### 2. Load CONTEXT.md (if present)

If `CONTEXT.md` exists at the project root, read it and pre-load any
term-blocks whose `Term` matches keywords in the area name (or whose
`Aliases to avoid` field hints at the area). Carry these terms forward
into the orientation report so the reader sees the vocabulary the
codebase actually uses.

If `CONTEXT.md` does not exist, skip silently — orientation still works,
just without the glossary anchor.

### 3. Map modules and callers

Run Glob + Grep to identify:

- **Entry points** — files in the area that other modules import (high
  fan-in: many `import`-ers).
- **State owners** — files that declare the area's persistent
  state (Zustand stores, Convex queries, libSQL tables).
- **External boundaries** — files that touch external systems (HTTP,
  IPC, native modules, child processes).
- **Known fragile areas** — search for `// TODO`, `// FIXME`, `// HACK`
  comments + any recent commits touching the area (last 30 days).

### 4. Emit the one-page orientation

Output to stdout (no file written — this is a read-only orientation):

```markdown
# Orientation: {area name}

## Purpose
{One paragraph: what does this area exist to do?}

## Entry points
- `{path}` — {one-line role}
- `{path}` — {one-line role}

## State owners
- `{path}` — {one-line: what state, what scope}

## External boundaries
- `{path}` — {one-line: which external system, what direction}

## Known fragile areas
- `{path}:{line}` — `// TODO` / `// FIXME` summary + age
- {recent-commit-shortlog one-liner if relevant}

## Glossary (from CONTEXT.md)
- **{Term}** — definition + aliases-to-avoid
- {…}

## Pointers for the next agent
- {one-line: where to start reading}
- {one-line: which test file to read first}
- {one-line: which CONTEXT.md term resolves the most ambiguity}
```

The orientation MUST fit on one screen. If it doesn't, you've gone too
deep — re-scope the area name and try again.

## Output contract

- **Read-only.** This skill never writes files. It is a context-loader,
  not a planner.
- **Stops at orientation.** Do NOT pivot into `/apt:plan` automatically.
  The user invokes `/apt:plan` (or `/apt:improve`) as a follow-up if the
  orientation surfaces a planning opportunity.
- **No grill posture.** This skill does NOT load
  `apt-discuss/appendices/grill-discipline.md` — orientation is
  descriptive, not normative. Locking decisions is `apt:discuss`'s job.
