/module-deepening

name: module-deepening
description: 'Use when looking for shallow modules worth deepening, deciding where a seam belongs, or designing a chosen module''s interface several ways before refactoring. Scan mode renders candidates as an offline HTML report; design mode compares alternative interfaces and recommends one. Asks one question at a time, stops at an agreed decision and never edits code. Triggers on: "find deepening opportunities", "shallow modules", "where should the seam go", "design it twice", "deepen this module", "make this testable through its interface", "AI-navigable codebase". NOT for scored multi-dimension architecture reviews, use architecture-reviewer. NOT for improvement plan backlogs, use codebase-advisor. NOT for local simplification, use code-refiner or /refactor. NOT for domain terminology, use domain-modeling.'
metadata:
  version: 1.0.1
  category: review
  tags: [architecture, deep-modules, seams, testability, interface-design]
  difficulty: advanced
  phase: review
  complements:
    - architecture-reviewer
    - domain-modeling
    - adr-writer
    - codebase-advisor

Module Deepening

Find **deepening opportunities**, refactors that turn shallow modules into deep ones, and decide the shape of one deepened module with the user. A deep module puts a lot of behaviour behind a small interface at a clean seam, so callers get leverage, maintainers get locality, and tests cross the same interface callers do. The aims are testability and AI-navigability: an agent should be able to understand and safely change one concept by reading one module.

This skill decides. It does not implement. Every session ends at an agreed decision (or an explicit rejection) and hands implementation to separate work.

When to Use

| Situation | Package | |---|---| | Find where shallow modules cause friction, or pick what to deepen next | `module-deepening` (scan) | | Shape the interface of one chosen module, or decide where its seam goes | `module-deepening` (design) | | Scored review across structure, scalability, security, performance, operations, data | `architecture-reviewer` | | Prioritized, agent-executable implementation plans for a repository | `codebase-advisor` | | Simplify a function or file without changing its interface | `code-refiner` or `/refactor` | | A domain term is ambiguous or code contradicts the domain model | `domain-modeling` | | Record a decision that already qualifies as an ADR | `adr-writer` |

Prerequisites and Authority

• **Read-only.** Read code, docs and git history. Never edit source, tests, configuration, `CONTEXT.md` or ADRs. The only file this skill writes is the scan report, and it goes to the OS temp directory, never into the repository.
• **Vocabulary.** Before either mode, read `references/vocabulary.md`. Use its terms exactly (module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality) in every question, card and recommendation. Do not drift into "component", "service", "API" or "boundary".
• **Domain language.** Read the project's domain context: `docs/agents/domain.md` when present (it routes to the authoritative files), then `CONTEXT.md` or `CONTEXT-MAP.md` and the context-local `CONTEXT.md` for the area in scope. Name modules after those concepts: "the Order intake module", not "the FooBarHandler" and not "the Order service". If no domain context exists, say so once and use the names the code already uses.
• **Decisions already made.** Read ADRs that touch the area, following the lookup route in `docs/agents/domain.md` or the repository's existing ADR directory. Do not re-litigate them unless the friction is real enough to warrant reopening (see the report's ADR callout rule).
• **Sub-agents.** Exploration and design-it-twice use sub-agents when the harness provides them (for example Claude Code's Task tool with a read-only exploration agent). Without them, follow each reference's sequential fallback and say which path ran.
• **Git.** Scan mode uses `git log` to find hot spots. Outside a git repository, ask the user for a direction, scan those files without history and record that hot-spot evidence is unavailable.

Interaction Contract (both modes)

1. Ask **one question at a time**, each with the options you see and your recommended answer. Wait for the answer before asking the next. Do not batch a questionnaire. 2. Walk the decision tree in order: constraints, dependencies and their category, the shape of the deepened module, what sits behind the seam, which tests survive. 3. Stop when the user agrees a decision (the candidate, the interface shape, the seam placement) or rejects the candidate. Do not continue into planning or implementation. 4. Never edit code, even if asked mid-session "just do it". Hand off instead (see Decision Handoffs).

Workflow

Select the mode

• The user named a module, a picked candidate or a seam question ("where should the seam go in X?") → **design mode**.
• The user asked where to deepen, named only a direction (a subsystem, a pain point) or named nothing → **scan mode**.
• Ambiguous → ask one question: "Do you want me to find candidates, or design the interface of a module you have in mind?"

Scan mode

1. **Scope before you scan (YAGNI).** Deepening pays off by making future change easier, so weight what changes. If the user named a direction, it is the scope; run `git log --oneline -n 200 --name-only -- <paths in that direction>` only to find the hot spots inside it. Otherwise run `git log --oneline -n 200 --name-only` over the whole repository (widen the window if the history is short or scattered) and list the files and directories that keep recurring. Outside a git repository, skip `git log` entirely: scope to the direction the user gave (ask for one if they gave none), inspect those files directly and record "hot-spot evidence unavailable: not a git repository". Record the scope, the hot spots you chose (or why there are none) and why. 2. **Rea