explore

name	explore
description	Graph-first codebase discovery → project-map.md. Use at session start on an unfamiliar project, or /explore. Not for root-cause analysis (analyze) or deriving a spec (reverse-document).

Explore

You map an unfamiliar project so everything downstream can route. You traverse graph-first — start at the high-value nodes (entry points, manifests, configs, test files, the dependency surface) and follow edges outward — rather than reading every file. The output is one durable project-map.md plus memory drawers, so the second session in this codebase does not re-discover it. Domain-neutral: the "codebase" may be source, a data project, a content repo, or a research corpus.

What this does / does not do

Does: seed from high-value nodes, traverse to a bounded depth, write a project-map.md (structure, entry points, conventions, risk files, where things live) and FRESH finding drawers, and a receipt. Does not: derive a spec from the code (that is reverse-document), diagnose a failure (analyze), modify any file, or read the whole repo when the high-signal subset answers the question.

When NOT to use

• The goal is a spec/task card from existing code — that is reverse-document, not a map.
• A fresh project-map.md already exists for this codebase and nothing has changed — reuse it (check staleness) instead of re-traversing.

Reference Routing

Situation	Reference
Drawer write delegation	library/systems/memory/drawer-writer.py
Receipt write delegation	engine/shared/references/script-delegation-contract.md
Avoid reading the whole repo (attention budget)	engine/shared/references/context-degradation.md

Inputs

Field	Required	Description
root	yes	the project root to map
depth	no	traversal bound (default: shallow — entry points + one hop)
refresh	no	force re-traverse even if a recent project-map.md exists

How to do it

Step 1 — Seed from high-value nodes

Identify the entry points and the dependency surface first: manifests (package/build files), configs, the main entry module(s), the test directory, the docs index. These are the graph's hubs — they reveal structure faster than a flat file walk.

Step 2 — Traverse outward, bounded

Follow imports/links/references from the seeds to depth. Record what you read (the evidence base). Respect the attention budget (context-degradation.md): read high-signal nodes, note the unread scope — do not load the whole tree.

Step 3 — Write project-map.md

Emit a map: directory structure with purpose, entry points, conventions observed (naming, error handling, test layout), risk/complex files, and "where to put X" guidance. Mark inferences as such.

Step 4 — Write finding drawers

Write the durable facts (conventions, architecture decisions observed, risk files) as FRESH memory drawers via drawer-writer.py, so they accrete (the next session benefits). Category by type (architecture / implementation / quality).

Step 5 — Receipt

Write the explore receipt (what was mapped, what was skipped, drawer count, staleness).

Output Contract

explore receipt (<workspace>/receipts/explore-receipt-<timestamp>.json): base + map_path, entry_points (array), conventions (array), risk_files (array), drawers_written, unread_scope, confidence. persistence: Spec-First. Second output: project-map.md at map_path.

Proactive Triggers

• The repo is large: respect depth; map the high-signal subset and record unread_scope — never attempt a full read (lost-in-the-middle degrades the map).
• A convention is observed in 3+ places: write it as a FRESH drawer — it is a durable project fact.
• A project-map.md exists but is STALE: re-traverse only the changed surface; do not discard the map.
• An inference about structure has no evidence: mark it inferred in the map; do not assert it.

Completion Criteria

Done when: project-map.md exists with entry points, structure, conventions, and risk files; finding drawers are written; a receipt records the mapped + unread scope.

Not done if: the whole repo was read into context instead of the high-signal subset; inferences were asserted as fact; no drawers were written (the map did not accrete); no receipt.

Next step: intake/recipe routes on the map; reverse-document can derive a spec from it; analyze can root-cause within it.

Related Skills

• reverse-document: Derives a spec from the code; explore produces the map. Different artifacts.
• analyze: Root-causes a failure within the mapped codebase. explore maps; analyze diagnoses.
• memory: The substrate explore writes findings into (drawers accrete across sessions).