Modular Decomposition

How the agent should run it

1. Scope: Confirm the task is structural analysis (inventory → coupling → grouping), not roadmap authoring. If unclear, ask once whether they want the full ordered pipeline or a subset.
2. Order: Run patterns 1 → 2 → 3 → 4 → 5 in that order. Do not skip a step unless the user explicitly limits scope; if they do, state which patterns were skipped and how that limits later conclusions.
3. Load references: For each pattern, open the matching references/pattern-NN-*.md file and follow its instructions. Use the optional *-quick-reference.md for the same number when a short checklist is enough.
4. Carry context forward: Reuse outputs from earlier patterns in later ones (e.g. component inventory from Pattern 1 informs coupling in 4 and grouping in 5). Reference concrete paths, modules, or tables from previous steps.
5. Domain language (Pattern 5): If subdomains or bounded contexts need grounding beyond structure, read references/domain-analysis.md before or alongside Pattern 5. Optionally open references/domain-analysis-quick-reference.md or references/domain-analysis-examples.md for condensed rules or illustrations.
6. Deliver: Produce clear, actionable findings per pattern or one consolidated report—always tied to evidence from the repository (files, dependencies, metrics), not generic advice.

Usage examples

Example 1 — Full pipeline

User: "We're going to split this monolith—run the full decomposition analysis (Patterns 1–5)."

Agent: Execute patterns 1→5 in order, loading each references/pattern-NN-*.md, preserving outputs between steps, then summarize cross-cutting recommendations.

Example 2 — Coupling after inventory

User: "We already have a rough module list—focus on coupling (Pattern 4) and then domain grouping (Pattern 5)."

Agent: If no prior inventory exists in the thread, either run Pattern 1 briefly or derive an explicit module list from the repo before 4 and 5. State any assumptions.

Example 3 — DDD before grouping

User: "Map bounded contexts and language, then group components into domains."

Agent: Read references/domain-analysis.md (and optional quick reference/examples) in parallel with or immediately before Pattern 5; align Pattern 5 groupings with linguistic boundaries where evidence supports it.

Prerequisites

• Complete Pattern N before starting Pattern N+1 unless the user explicitly narrows scope. Later patterns depend on earlier results (for example, inventory and structure inform coupling and grouping).
• If business vocabulary, subdomains, or bounded contexts are uncertain, use references/domain-analysis.md before or alongside Pattern 5 (see Bounded contexts below).

Ordered workflow (Patterns 1–5)

Pattern 6 — planning and extraction

Pattern 6 (create domain services / extraction) is not duplicated here. After Pattern 5, switch to decomposition-planning-roadmap for phased extraction order, milestones, and migration-style planning. For full legacy migration strategy (strangler-fig, cross-stack rewrites, research-heavy plans), optionally use legacy-migration-planner in addition.

Bounded contexts and DDD strategic design

• Patterns 1–4 focus on structural inventory, duplication, hierarchy, and coupling between parts of the codebase.
• Pattern 5 produces candidate groupings aligned with solution-space boundaries (which components belong together as services).
• Strategic DDD (subdomains, bounded contexts, ubiquitous language) is covered in references/domain-analysis.md, with optional domain-analysis-quick-reference.md and domain-analysis-examples.md. Use it when you need to validate or refine boundaries against business language, not only folder structure.