explore-module

name	explore-module
description	Use when starting work in an unfamiliar module, when a module's `.context.md` is missing or stale, or when asked to document or understand a module's role

/explore-module — Build or Update .context.md

.context.md is the module's memory. Read it first; explore from scratch only when it's missing or stale. This skill creates and maintains those files so understanding survives across sessions.

---

Workflow

1. Identify module    — /explore-module [path]  (or interactive)
2. Check .context.md
     present + recent (< 2 weeks)  → read it; you understand the module
     present + stale  (> 2 weeks)  → read for baseline, then update outdated sections
     missing                       → full exploration (step 3)
3. Explore (only if needed) — dispatch the built-in Explore agent ("very thorough")
   so the raw file reads stay out of the main context; its brief:
     - read entry points, public interfaces, index/barrel files
     - trace exports / public functions / API endpoints
     - identify dependencies (internal + external)
     - git log --oneline -20 -- [path]
     - read tests for behavioral expectations
     - RETURN: findings structured per the template below
4. Write/update .context.md (template below)
5. Verify accuracy   — purpose clear, key files complete, no phantom dependencies

---

Template

# Module: [name]

**Last Updated:** [YYYY-MM-DD]
**Status:** Active | Stable | Deprecated | Refactoring

## Purpose
1–2 sentences: what this module does and why it exists.

## Key Files
| File | Purpose |
|---|---|

## Public Interfaces
| Symbol | Signature | Description |
|---|---|---|

## Dependencies
**Internal:** module — what we use
**External:** package — what we use

## Architecture Notes
Key design decisions, patterns, invariants.

## Recent Changes
- YYYY-MM-DD: what + why

## Known Issues
- open problems / tech debt

---

Maintenance rules

• One .context.md per module directory (not per file).
• Keep it under ~100 lines. If longer, you're documenting too much.
• Always include Last Updated so staleness is visible.
• Checked into version control — it's part of the codebase.
• Don't put obvious-from-code details, debug notes, TODOs, or generated API docs here.

---

When to refresh

• Before starting work on a module: read first, always.
• After implementation: update Key Files, Public Interfaces, Recent Changes.
• After refactoring: update Architecture Notes and Dependencies.