| name | inspect-module |
| description | Use this skill whenever the user mentions "explore", "inspect", "understand", "what does X do", "where is Y", or before adding a new feature in an unfamiliar area. Produces a structured map of one module — files, exports, dependencies, layer assignment, and recent commits — without reading the entire codebase. Always invoke this skill before editing an unfamiliar module so the agent has accurate context, not guesses. |
| allowed-tools | Read, Glob, Grep, Bash(git log:*), Bash(git ls-tree:*), Bash(tree:*), Bash(node .claude/skills/inspect-module/scripts/module-summary.mjs:*) |
| suggested-turns | 6 |
When to use
The user asked any of: "how does X work", "what's in src/foo", "before I add
feature Y, what's in the area?", "explore ", "show me the shape of
".
Steps
-
Resolve the target. If the user gave a feature name (not a path), grep
.harness/feature_list.json for it. If multiple paths match, ask the user which.
-
One-shot summary (deterministic). Run the side-car script — bundles
target kind + layer + recent commits, and for module targets also exports +
inbound + outbound deps, into one JSON blob, replacing three LLM turns of grep:
node .claude/skills/inspect-module/scripts/module-summary.mjs <target>
Read the JSON. If targetKind is workspace, render a workspace overview
from workspace.domains and do not warn about layer: null. If targetKind
is unlayered, the path is outside any configured layer root — flag that
and ask whether the user wants to add it. If targetKind is module, use
the reported layer normally.
-
Forward-only check. For targetKind: "module", walk outbound[] and verify each crosses layers
forward only (never backward). The structural test enforces this
mechanically too, but flagging here short-circuits a wasted write step.
-
Risks. Flag any of: dynamic imports, eval, shell-out with
interpolation, missing tests for an exported function. (LLM judgment —
the side-car reports facts, not risks.)
Output contract
Produce a Markdown report with these sections, in this order:
For targetKind: "workspace":
### Module: workspace overview
### Layer: workspace overview
### Domains: <domain roots and layers>
### Recent changes: <top 3 commit messages>
### Risks: <bulleted list, "none" if clean>
For module or unlayered targets:
### Module: <path>
### Layer: <layer-name or unlayered>
### Public surface: <list>
### Inbound deps: <list of paths>
### Outbound deps: <list of paths or external packages>
### Recent changes: <top 3 commit messages>
### Risks: <bulleted list, "none" if clean>
End with: "I am ready to make changes to <module>. The architecture-reviewer
subagent will be invoked on completion."
Anti-patterns
- Don't read every file in the module — sample exports, then drill in only
where the user's task points.
- Don't propose changes in this skill. This is read-only context-gathering.
