---
name: loom-codebase-atlas
description: "Use when an unfamiliar code area needs a reusable map of modules, callers, interfaces, data flow, constraints, and related records before safe implementation, review, debugging, or planning."
---

# loom-codebase-atlas

Codebase atlas is a zoom-out playbook.

It maps a relevant code area in terms of domain language, modules, callers,
interfaces, and decisions, then records accepted reusable context in knowledge.

## Core Dependency

Use `loom-core` first. This playbook composes `loom-knowledge`,
`loom-research`, `loom-constitution`, `loom-specs`, `loom-evidence`, and
`loom-tickets`.

It explains the codebase. It does not replace specs, tickets, evidence, or audit.

## Use This Playbook When

Use this playbook when:

- the agent is unfamiliar with a code area
- a ticket needs context before safe execution
- a bug or review requires caller/callee understanding
- a plan depends on module relationships
- architecture terms need grounding in actual code
- a future agent would benefit from a persistent map

Skip it when a narrow file read is enough to complete a small scoped edit safely.

## Route

Use this route:

```text
question -> scope -> map -> explain -> record -> route
```

## Question

Start with the reason for the atlas.

Examples:

- Where does this behavior enter the system?
- Which modules call this interface?
- What owns this data lifecycle?
- Which code paths must a worker understand before editing?
- Why does this area feel tangled?

The atlas should answer a retrieval need, not become a full repository tour.

## Scope

Bound the map by task, domain, interface, feature, or failure.

Inspect:

- relevant knowledge, specs, decisions, tickets, and evidence
- source files and tests around the area
- public interfaces and callers
- data flow and side effects
- setup, generated files, or external dependencies only when relevant

Use project domain vocabulary when it exists. If language is missing or confused,
route through `loom-domain-language-and-decisions`.

## Map

Describe the area in layers that help future work:

- domain concepts involved
- modules and their roles
- entry points and callers
- interfaces and invariants callers must know
- important side effects, state, data ownership, or lifecycle rules
- tests and evidence that cover the area
- decisions or specs that constrain changes
- known seams, adapters, or extension points
- gaps, unknowns, and risky assumptions

Prefer a compact map over exhaustive file listings. File paths are useful when they
help navigation, but the atlas should explain relationships.

## Explain

Give the operator or future agent the higher-level picture:

- what to read first
- what not to change casually
- which names map to domain concepts
- where behavior is concentrated
- where behavior is scattered
- what would make the next change safer

If the map reveals architectural friction, route to `loom-architecture-deepening`.
If it reveals missing behavior contracts, route to `loom-specs`.

## Record

Create or update a `Knowledge Atlas` when the map should survive the session.

The atlas should include:

- task or domain triggers for retrieval
- applies-to paths or areas
- module/caller map
- key interfaces and invariants
- related specs, decisions, tickets, evidence, or research
- boundaries where the atlas stops applying
- freshness note when the code area changes quickly

Do not promote uncertain exploration as accepted knowledge. Use research or
evidence for unresolved observations.

## Done Means

The atlas pass is done when:

- the original zoom-out question is answered
- relevant modules and callers are mapped at the right level
- durable context is recorded when useful
- unknowns and risks are explicit
- the next work route is clear