Use domain modeling and codebase design in Patchmill planning

[rochecompaan]

Problem

Patchmill planning does not currently require domain modeling or explicit
codebase-design analysis while developing a specification.

Plan review focuses on completeness, spec alignment, task decomposition, and
buildability. It does not require the reviewer to inspect the existing
architecture or verify that the plan produces well-designed, deep modules.

A specification or plan can therefore pass review while it:

• uses domain terms inconsistently;
• conflicts with existing domain documentation or ADRs;
• assigns unclear ownership to domain concepts;
• spreads related behavior across shallow modules;
• exposes implementation details through large interfaces; or
• introduces unnecessary seams and adapters.

Required behavior

Develop specifications using domain modeling

When a specification defines or changes architecture, the Patchmill planning
skill must use the Matt Pocock domain-modeling skill.

While developing the current specification, the planner must:

• read CONTEXT.md and CONTEXT-MAP.md when present;
• read relevant ADRs;
• use established domain language consistently;
• identify ambiguous, overloaded, or conflicting domain terms;
• cross-check proposed domain behavior against the existing code;
• identify the relevant domain contexts and their relationships;
• update domain documentation when planning resolves a domain term; and
• surface conflicts with existing ADRs instead of silently overriding them.

Do not create domain documentation merely as ceremony. Create or update it only
when planning resolves a domain concept or architectural decision.

Develop architecture using codebase design

When a specification defines or changes modules or their interfaces, the
planning skill must use the Matt Pocock codebase-design skill.

Use its architecture vocabulary consistently:

• module
• interface
• depth
• seam
• adapter
• leverage
• locality

The specification must explain:

• which modules own the affected domain behavior;
• what each module's interface requires callers to know;
• which implementation details remain hidden;
• where seams and adapters belong;
• how dependencies enter the modules;
• how the design improves or preserves locality and leverage; and
• how behavior will be tested through module interfaces.

The design should favor deep modules: substantial behavior behind a small
interface at a clean seam.

Make architecture analysis part of plan review

Plan review must independently inspect the relevant codebase. It must not rely
only on the specification and plan.

Before approving a plan, the reviewer must determine the relevant existing
architecture, including:

• the domain concepts and language involved;
• the current modules and their interfaces;
• the important seams and adapters;
• responsibilities and files that change together;
• dependencies between modules;
• relevant domain documentation and ADRs; and
• current test surfaces.

The reviewer must then determine whether the plan:

• follows or deliberately improves the domain model;
• gives each domain concept clear ownership;
• preserves or improves locality and leverage;
• creates deep modules rather than shallow pass-through modules;
• keeps interfaces smaller than the complexity they hide;
• places seams where behavior genuinely varies;
• avoids exposing internal seams through public interfaces;
• introduces adapters only when real variation justifies them;
• accepts dependencies instead of constructing them internally; and
• tests observable behavior through module interfaces.

The reviewer must apply these codebase-design principles:

• the deletion test;
• the interface is the test surface; and
• one adapter is a hypothetical seam, while two adapters establish a real seam.

Blocking findings must cite concrete codebase evidence, such as files, symbols,
call flows, interfaces, seams, or ADRs.

Acceptance criteria

• Patchmill planning uses Matt Pocock domain-modeling while developing a
  specification that defines or changes architecture.
• Patchmill planning uses Matt Pocock codebase-design when specifying
  modules, interfaces, seams, or adapters.
• Specifications follow existing domain documentation and relevant ADRs.
• Specifications describe module ownership, interfaces, hidden
  implementation, dependencies, and test surfaces.
• Plan review independently determines the relevant existing codebase
  architecture.
• The review rubric checks module depth, interface size, seam placement,
  adapter justification, locality, leverage, and test surfaces.
• Blocking architecture findings include concrete codebase evidence.
• Changes that do not define or alter architecture are not forced to create
  unnecessary domain artifacts.
• The required Matt Pocock skills are available wherever the managed
  Patchmill planning workflow runs.
• Skill-pack configuration, metadata, tests, and live dependency references
  resolve the same Matt Pocock skills version.
• Documentation explains the new planning and review requirements.

References

Matt Pocock skills:

• engineering/domain-modeling
• engineering/codebase-design
• engineering/codebase-design/DEEPENING.md