Deepen a module

The goal is to hide accidental complexity: the codebase knows the module's entry and nothing behind it, as if it were a package that has not been published.

A building block is not a deep module: a module other modules are built from, one job, several callers, no module document of its own. It still has an entry, held to the same rule as a deep module's (The entry, below).

One module document per module, written from the first finding, never in chat. Through the aiview skill: kind module, file YYYY-MM-DD-<module>.module.md, tags = module name, in the plan's group when a plan waits on it. Each stage below writes its sections into it.

Discover

For an existing module, discover its actual boundaries before designing. Its code may be scattered across the codebase. Document its files, its callers and its application dependencies in Today. A new module starts at Design.

Design

Sections in this order, each marked provisional where an open decision could change it.

1. Usage: the complete code a caller writes to use the module; for a component, its tag with its inputs and outputs. It carries the caller's intent and no accidental complexity: no wiring, ordering, configuration or knowledge of internals.
2. The entry: one logical public entry point per case the callers are in: a file, a component, a factory or a package entry. Callers bound by different rules get an entry each, named for their case, over a core they cannot import. All public access goes through an entry, each surface stays cohesive, and each is written as signatures without bodies.
3. Outside: what stays in the project: its data, and the one binding that passes the project's names to the module.
4. The conditions, each marked held or broken today:
   • all access to the module goes through the entry
   • the module imports nothing from the application, and receives any collaborator it drives
   • it reads no environment and no global state
   • every project-specific name, path or setting is an option with a working default
   • its tuning numbers (a limit, a retry count, a default, a threshold) are named once in one constants file beside its entry, never written as a literal in a branch or a schema bound
   • its tests go through the entry only, and a boundary test enforces these conditions
5. The gap: what changes from Today to reach the design: exports, imports, and every caller. Changing the callers is part of the work. A large gap is drawn, who depends on whom before and after, through the write-diagrams skill.
6. The open decisions, numbered, each with its options and a recommendation.

Discuss

Resolve the open decisions with the interview skill, writing each answer into the section it changes. Challenge every export: what no caller clearly needs stays inside.

Agree

The document is agreed when the list is empty and the person says so. The date goes in its header, and the entry is frozen: a later change to it is a new decision.

Implement

The rework is a task, and it quotes the agreed entry word for word.

Red flags