zoom-out

Files (1)

• SKILL.md

SKILL.md (first lines)

# Zoom Out

## When to use this skill

Use this skill when the current edit window is too low to make a sound design call — you need to see callers, public API surface, or the module boundary one layer above where you are looking. The trigger is "I am unfamiliar with this area" OR "this fix may belong somewhere else." Output is a short reframe paragraph plus a recommendation to keep zooming out or commit the current altitude.

## Adapted From Upstream

This adapter is derived from
[`zoom-out/SKILL.md`](../../upstream/mattpocock-skills/zoom-out/SKILL.md) in
the `mattpocock/skills` submodule pinned at
`90ea8eec03d4ae8f43427aaf6fe4722653561a42`. The upstream is a single-line
prompt that says *"I don't know this area of code well. Go up a layer of
abstraction. Give me a map of all the relevant modules and callers."*

To read the upstream body without loading the full file, prefer:

```text
nav_read_anchor SKILLS/upstream/mattpocock-skills/zoom-out/SKILL.md <anchor-id>
```

License: MIT, Copyright (c) 2026 Matt Pocock. See repo-root `NOTICE` and
`SKILLS/upstream/mattpocock-skills/LICENSE`.

## EVOKORE-Specific Adaptations

Concrete deltas vs the upstream prompt:

- **No "ask the user" loop.** The upstream prompt assumes a human in the
  loop will provide the higher-level framing. EVOKORE is autonomous — this
  adapter reads prior artifacts instead: the in-flight diff
  (`git diff --staged`), the active session manifest at
  `~/.evokore/sessions/{sessionId}.json`, the replay log at
  `~/.evokore/sessions/{sessionId}-replay.jsonl`, and any evidence already
  captured at `~/.evokore/sessions/{sessionId}-evidence.jsonl`.
- **`nav_get_map` substitution for "give me a map".** Where the upstream
  asks the human to provide a map of modules and callers, EVOKORE calls
  the native `nav_get_map` tool against the file under edit (and any
  obvious caller files surfaced by `git grep`) to get a token-efficient
  anchor map without loading whole files.
- **Bounded-context awareness.** When the file under edit lives inside a
  bounded context defined in `docs/adr/0005-bounded-contexts.md`, the
  reframe must name that context explicitly. Going up one layer of
  abstraction inside `Session & Continuity` is different from going up
  one layer inside `Skill Registry & Discovery`; the seam choice
  depends on which context's invariants apply.
- **Composition phrasing for downstream skills.** When the reframe
  recommends a follow-up, this adapter emits the literal phrasing the
  static composition graph parses (e.g., "invoke ubiquitous-language skill"
  or "invoke docs-architect skill") so `derive-skill-composition.js` can
  edge to the correct next step.
- **Trigger-explicit description.** Frontmatter `description` is rewritten
  from the upstream noun-ish phrasing into EVOKORE's "Use when ..." form so
  `resolve_workflow` semantic ranking can find this skill above deep
  reference leaves.

## Composition

- **Callers (skills that should invoke this skill):**
  - `simplify` — when a proposed simplification touches a public seam,
    invoke zoom-out skill first to confirm the seam is actually public.
  - `repo-ingestor` — early in a fresh-repo onboarding, invoke zoom-out
    skill to surface module boundaries before deeper analysis.
  - `orch-plan` — when a slice plan straddles an unclear module boundary,
    invoke zoom-out skill before locking the slice scope.

- **Callees (skills this skill may invoke):**
  - After zoom-out has identified a candidate seam, optionally invoke
    docs-architect skill to ensure the surface change is documented.
  - When the higher-altitude reframe reveals genuine domain ambiguity
    (e.g., two callers use "session" to mean different things), invoke
    ubiquitous-language skill (scoped to the relevant bounded context
    from `docs/adr/0005-bounded-contexts.md`).

## Procedure

1. **Identify the focus file(s).** Read the in-flight diff
   (`git diff --staged`, then `git diff` if nothing staged). If there is
   no diff, fall back to the file path the user named. Record the
   focus file(s) explicitly.

2. **Surface the local anchor map.** Call `nav_get_map` on each focus
   file. This returns a structured anchor list at ~100 tokens vs 4K-40K
   for a full file read. If the focus file has no `@AI:NAV` anchors,
   note it and continue (the absence is itself a signal — files without
   anchors tend to be the inner leaves, which is the wrong altitude
   for zoom-out by definition).

3. **Map callers.** Run `git grep -n "<exported-symbol>" -- 'src/**/*.ts'`
   for each public symbol in the focus file(s). Record at most ten
   caller hits — if there are more, the file is genuinely a hub and that
   fact becomes part of the reframe.

4. **Identify the bounded context.** Read
   `docs/adr/0005-bounded-contexts.md` (or `nav_read_anchor` it if
   anchored) and determine which bounded context the focus file belongs
   to. State the context name explicitly. If the focus file straddles
   contexts (e.g., it imports from two different contexts' modules),
   call that out — the seam may need to live at the context boundary.

5. **Write the reframe.** Emit one paragraph that answers three
   questions:
   - What layer is the focus file at? (leaf / module-internal / public
     surface / cross-context boundary)
   - What lives at the layer above? (callers, public API, MCP-surfaced
     tool definition, ADR-defined context boundary)
   - At which layer does the proposed change actually belong?

6. **Recommend next step.** End the reframe with a single recommendation:
   - `COMMIT-ALTITUDE` — the current edit window IS the right altitude;
     proceed with the change.
   - `ZOOM-FURTHER` — the change belongs higher up; restart at the
     caller's caller, or at the public API.
   - `ZOOM-IN` — the framing was already too high; drop into the named
     leaf module.
   - Optionally append "invoke X skill" pointing at the next skill the
     caller should run.

## Inputs and Outputs

From mattmre/EVOKORE-MCP-PUBLIC, MIT.

More from mattmre/EVOKORE-MCP-PUBLIC