REFACTOR EXTRACTION (8-COMMIT PER-ENTITY)

refactor-extraction.md

Per-entity large-refactor template with IDOR matrix discipline. The shape that keeps cross-tenant boundaries intact during code reshuffles.

Stark

WHAT THIS PATTERN TEACHES

How to split a 1,000+ LOC router/service/handler file in N commits without losing review traction. Architecture-quick plan, entity inventory, per-commit IDOR matrix, final cleanup. Each commit independently shippable with green tests.

WHEN TO USE THIS

Any time a router/service file >1,000 LOC needs splitting AND the project has an exit gate (max-LOC-per-file). Surfaces route-shadow bugs and IDOR gaps that single-commit refactors mask in diff noise.

AT A GLANCE

# Commit plan (one per entity + scaffold + cleanup)
| # | Commit | Cumulative LOC |
|---|--------|----------------|
| 1 | scaffold | 1861 |
| 2 | extract people | 1694 |
| 8 | cleanup | 597 |

FRAMEWORK IMPLEMENTATIONS

Markdown

# Refactor: <topic> — extraction plan
# (write to logs/reviews/<topic>-architecture.md BEFORE any commit)

## Current state
- Source file: <path> at <LOC>
- Exit gate: <LOC limit>
- LOC delta needed: <gate - current>

## Entity inventory
| Entity | Endpoints | Estimated LOC delta |
|---|---|---|
| people | 7 | -167 |
| companies | 10 | -345 |
| | **Total** | **−1264** |

## Commit plan
| # | Commit | Adds | Removes | Cumulative LOC |
|---|---|---|---|---|
| 1 | scaffold (service base, error types, shared helpers) | services/_base.py | — | 1861 |
| 2 | extract people | services/people_service.py | router code | 1694 |

← All Patterns