---
name: loom-architecture-deepening
description: "Use when architecture work is about increasing module depth, leverage, locality, test seams, or caller simplicity in tangled or shallow code, not local readability cleanup."
---

# loom-architecture-deepening

Architecture deepening is a refactoring-shaping playbook.

It looks for places where a better module interface can hide more behavior, improve
locality, and make tests and future agent work easier.

## Core Dependency

Use `loom-core` first. This playbook composes `loom-codebase-atlas`,
`loom-domain-language-and-decisions`, `loom-code-simplification`,
`loom-api-and-interface-design`, `loom-specs`, `loom-plans`, `loom-tickets`,
`loom-evidence`, and `loom-audit`.

It proposes and shapes refactors. Execution still belongs in tickets and evidence.

## Use This Playbook When

Use this playbook when:

- understanding one concept requires bouncing through many small modules
- a module's interface is nearly as complex as its implementation
- tests reach past interfaces into implementation details
- pure helpers were extracted for testability but bugs live in orchestration
- callers repeat the same policy, ordering, validation, or error handling
- an interface change could concentrate behavior and improve leverage
- the operator asks for architecture improvement rather than local cleanup

Skip it for simple readability cleanup that `loom-code-simplification` can handle.

## Route

Use this route:

```text
atlas -> candidates -> select -> design seams -> plan -> execute -> verify
```

## Language

Use these terms consistently:

- module: anything with an interface and implementation
- interface: everything a caller must know, including invariants, ordering, errors,
  config, and performance expectations
- implementation: code inside the module
- seam: where an interface lives and behavior can vary
- adapter: a concrete implementation at a seam
- depth: leverage at the interface
- locality: change, bugs, and knowledge concentrated in one place

Avoid using vague words like component or service when module, interface, seam, or
adapter is more precise.

## Atlas

Start with `loom-codebase-atlas` when the area is not already understood.

Read relevant:

- domain language and knowledge atlases
- constitution decisions and specs
- tests and current evidence
- callers and public interfaces
- code paths where behavior is duplicated or scattered

Do not relitigate an active constitution decision unless real friction makes it
worth reopening.

## Candidates

Present a short numbered list of deepening candidates.

For each candidate, include:

- files or modules involved
- current friction
- proposed module/interface direction in plain English
- expected leverage for callers
- expected locality for maintainers
- testing improvement
- risks, open questions, or decision conflicts

Use the deletion test: if deleting the module makes complexity vanish, it may be a
pass-through. If deleting it would push complexity into many callers, it may be
earning its keep.

Do not jump straight into implementation. Ask which candidate to explore.

## Design Seams

For the selected candidate, classify dependencies:

- in-process: pure computation or in-memory state
- local-substitutable: dependency has a realistic local test stand-in
- remote-owned: an owned service across a network or process boundary
- true external: third-party system outside project control

Use seam discipline:

- one adapter means a hypothetical seam
- two adapters usually make a real seam
- expose only the interface callers need
- keep internal seams internal when only the module's tests need them
- test through the interface when the interface is the real behavior surface

When interface shape is uncertain, design it twice. Compare two or more interface
options by leverage, locality, caller simplicity, dependency strategy, and test
surface before choosing.

## Plan

Route chosen architecture work to Core records:

- specs for durable behavior or interface contracts
- constitution decisions for hard-to-reverse precedent
- plans for multi-ticket sequencing or migration
- tickets for bounded implementation slices
- evidence for current behavior and post-refactor checks
- audit for broad, subtle, or high-risk refactors

Separate behavior-preserving deepening from feature changes unless the plan records
why bundling is still reviewable.

## Execute And Verify

Use `loom-incremental-implementation` or Ralph packets for execution.

Verification should prove:

- existing behavior is preserved or intentionally changed through specs
- tests now exercise the intended interface instead of implementation details
- duplicate caller logic moved behind the chosen interface
- old shallow tests or wrappers were removed only when replacement coverage exists
- audit reviewed hidden coupling and evidence sufficiency

## Done Means

The architecture deepening pass is done when:

- the friction was mapped before refactoring
- candidates were compared with leverage and locality in mind
- chosen seams and interfaces are explicit
- durable decisions and behavior contracts are recorded where needed
- implementation is sliced into tickets or packets
- evidence and audit can support the refactor claim