polyflow-improve-architecture

name	polyflow-improve-architecture
description	Identify refactoring opportunities by surfacing architectural friction. Apply the deletion test, deep-modules vocabulary, and seams analysis. Each opportunity becomes its own polyflow-writing-plans cycle. Use when reviewing code for refactoring, when a file has grown too large, or when architecture concerns surface during feature work.

PolyFlow: Improve Architecture

Vocabulary

See polyflow meta-skill. Key terms: module, interface, depth, seam, adapter, deletion test.

When to Use

• "This file is too big" / "this is hard to follow"
• A feature plan reveals friction the existing structure can't accommodate cleanly
• Periodic architectural review (Phase D of PolyFlow rollout)
• After tests reveal a module has the wrong shape

SKIP when: the user is doing a small, well-scoped change. Don't try to refactor adjacent code.

The Flow

1. Read Context First

• CONTEXT.md (if it exists) — for canonical domain language
• docs/adr/ — for prior architectural decisions you must respect
• The target file(s) and their direct callers

2. Identify Candidates

Walk the codebase noting friction:

• A concept that bounces across many modules to be understood
• An interface that rivals its implementation in complexity
• Files that have grown unwieldy (>400 lines is a smell, >800 is a klaxon)
• Conditional logic that branches by concept (suggests two adapters in a missing seam)

3. Apply the Deletion Test

For each candidate module: "If I deleted this, where would the complexity go?"

• Vanishes → the module is bloat; delete it
• Concentrates across N callers → the module earns its existence; preserve and possibly deepen it
• Moves to one place → the module is a thin pass-through; consider folding it

4. Embedded Grill — Candidate Selection

Before proposing changes, stress-test:

• "Which candidate has the highest leverage (improves most caller code)?"
• "Which candidate is safest to change (smallest blast radius)?"
• "Are there ADRs that constrain the design we're considering?"
• "Does the proposed deepening match domain language in CONTEXT.md, or are we inventing new terms?"
• "If we change this seam, will it require touching tests that currently bypass the interface? (If yes, the test design is also wrong.)"

5. Present Opportunities

For each, name:

• File(s) affected
• Current shape (what's wrong)
• Proposed shape (small interface, complex internals)
• Benefits (in domain language from CONTEXT.md)
• Cost (estimated PRs, blast radius)

Prioritize. Recommend ONE to tackle next.

6. Hand Off Per Opportunity

Each opportunity becomes its own polyflow-writing-plans cycle. Do not bundle multiple refactors into one plan — that's a horizontal-slice failure.

If the opportunity changes a public interface, route through polyflow-design-interface first.

Hard Rules

• Read CONTEXT.md and docs/adr/ before proposing changes. Domain language and prior decisions must inform the design.
• Deletion test first. Don't add abstractions just because they feel cleaner.
• One refactor per plan. Bundling refactors hides their individual value and inflates risk.
• Two adapters before a seam. Don't introduce variation points hypothetically — wait until two real implementations exist.
• Never auto-commit. Refactor PRs are easy to slip past review when batched; keep them small and explicit.

Hand-offs

• Opportunity selected → polyflow-design-interface (if interface changes) or polyflow-writing-plans (otherwise)
• New domain term emerged during discussion → polyflow-glossary to update CONTEXT.md
• Decision behind the design merits an ADR → write under docs/adr/