```bash git bisect start git bisect bad HEAD git bisect good {last_good_commit} git revert {bad_commit} # If unfixable # OR spawn generic-development to fix ```

**Standard file (< 10k lines, > 30% test coverage):** | Phase | Model | Tokens | Cost | |-------|-------|--------|------| | A: LLM Readability Map | Sonnet+thinking | 40k | 33x | | B: Layer separation (5 modules) | Sonnet | 5×30k = 150k | 8x | | C: LLM Cleanup (15 chunks) | Haiku | 15×10k = 150k | 1x | | D: Verification | Sonnet+thinking | 40k | 33x | | E: ARCHITECTURE.md (5 files) | Haiku | 5×5k = 25k | 1x | **Total:** ~405k tokens, **Cost: ~120x baseline** ---

- Phase C chunks within same module (independent) - Phase B modules WITHOUT shared dependencies - Phase D for non-critical modules - Phase E for independent modules **Example execution plan:** ``` Phase A: [SEQUENTIAL] └── generic-balanced-thinking: Create LLM Readability Map (1 agent) Phase B: [MOSTLY SEQUENTIAL] ├── Domain extraction ─────────────────────► BLOCKS all ├── Application (depends on domain) ────────► After domain ├── Infrastructure (implements domain) ─────► After domain └──...

- Phase A → Phase B (map before split) - Phase B modules with dependencies - Phase D for critical modules - Database migrations (ALWAYS blocking) - Phase E (ARCHITECTURE.md) → after Phase D verifies

**Imports (from file header):** ```php {import_block} ``` **Types/Interfaces Used:** ```php {relevant_types} ``` **Functions Called by This Chunk:** ```php {function_signatures_only} ``` **THIS CHUNK ({start_line}-{end_line}):** ```php {actual_code} ``` ``` ---

```markdown

| File Size | Chunk Size | Context Included | |-----------|------------|------------------| | 1-3k lines | Full file | All imports/types | | 3-10k lines | 400-600 lines | Imports + called functions | | 10-30k lines | 200-400 lines | Imports + direct neighbors only |

**NEVER give full 10k+ line file to agent. Instead:**

**This step is NOT optional. You MUST complete it before reporting "done" to the user.** After ALL modules verified (score B or better): ```bash # Final validation php artisan optimize:clear php artisan test ./vendor/bin/pint # MANDATORY: Archive refactor map mkdir -p coordination/refactor-maps/_archive/ mv coordination/refactor-maps/{filename}-refactor-map.md \ coordination/refactor-maps/_archive/ # Archive original plan if exists # mv coordination/refactoring/......

- **Why {pattern}:** {business or technical reason} - **Why NOT {alternative}:** {reason} ``` Commit: `docs({module}): Add ARCHITECTURE.md for LLM onboarding` ```

- **Depends on:** {module list} - **Depended on by:** {module list} - **External I/O:** {DB tables / HTTP endpoints / queues — or "None (pure domain)"}

| Class | Method | Called From | |-------|--------|-------------| | {Class} | {method} | {where} |

- {What must always be true about the state this module manages} - {What this module never does (negative invariants)}

{Numbered steps or ASCII diagram showing how data moves through this module} Example: 1. Request arrives at {EntryClass::method} 2. Input validated and mapped to {InputDTO} 3. {DomainService} calculates {result} 4. {Repository} persists via {table} 5. {OutputDTO} returned to caller

{DOMAIN / APPLICATION / INFRASTRUCTURE / PRESENTATION} {One sentence: why this code belongs in this layer.}

{One paragraph: what business problem this module solves. Written for a new LLM that has never seen this codebase.}

**Module Directory:** {path} **Files in module:** {file_list} **Layer:** {DOMAIN / APPLICATION / INFRASTRUCTURE} Create `{path}/ARCHITECTURE.md` with: ```markdown # {Module Name}

**Model:** `generic-light` (Haiku, 1x) — always **For EACH major module directory, spawn agent:** ```markdown

**Semantic Status:** ✅ PASSED / ⚠️ ISSUES / ❌ FAILED **LLM Readability Score:** A / B / C / D / F **Score Breakdown:** 1. One-sentence description: YES/NO — "{actual description}" 2. Single concern per function: YES/NO — "{issue if NO}" 3. Explicit dependencies: YES/NO 4. One error strategy: YES/NO 5. Domain-aligned naming: YES/NO 6. ARCHITECTURE.md exists: YES/NO 7. DTOs for core structures: YES/NO/N/A 8. Correct dependency direction: YES/NO **Semantic Issues:** {list or...

```markdown

**Part 1: Semantic Correctness** 1. **Invariants Preserved?** - Run: `git diff {first_commit}..HEAD -- {files}` - Check: All contracts from DO-NOT-CHANGE list 2. **Side Effects Unchanged?** - Compare: Before/after database queries - Compare: Before/after external API calls - Compare: Before/after file operations 3. **Error Handling Complete?** - All exceptions still caught? - Error messages unchanged? **Part 2: LLM Readability Score** Answer each question YES/NO: 1....

**Original File:** {original_path} **Refactored Files:** {new_paths} **Total Commits:** {commit_count}

**Choose agent:** - Standard verification → `generic-balanced-thinking` (33x) - Critical/scary code → `generic-heavy` (163x) ```markdown

``` refactor({module}): Introduce {DTO name} for {data structure} refactor({module}): Rename functions to express business intent refactor({module}): Separate I/O from domain logic in {area} refactor({module}): Standardize error handling to exceptions ``` ```

❌ Change function signatures ❌ Modify return types ❌ Add/remove side effects ❌ Change exception types ❌ Reorder initialization ❌ Change log formats

**Priority 1 — Highest LLM Impact:** ✅ Introduce DTOs for mystery meat arrays (from Phase A inventory) ✅ Rename functions to express intention: `verb + noun describing business concept` ✅ Extract mixed I/O+logic functions: one function = one concern ✅ Standardize error handling: pick ONE strategy and apply throughout **Priority 2 — Medium LLM Impact:** ✅ Split functions > 40 lines into named sub-functions ✅ Make dependencies explicit (no hidden static calls, no global state reads) ✅ Add PHP...

These elements MUST NOT be modified: - Signatures: {list} - Return types: {list} - Side effects: {list} - Exception types: {list}

**File:** {file_path} **Lines:** {start_line} - {end_line} **Layer:** {DOMAIN / APPLICATION / INFRASTRUCTURE}

**For EACH extracted module:** **Choose agent:** - DTO introduction / mechanical → `generic-light` (1x) - Error strategy / control flow reasoning → `generic-fast-thinking` (4x) **Chunk the module** (200-400 lines per chunk for LLM sweet spot): ```markdown

``` refactor({module}): Extract {module_name} to {layer} layer - Layer: {DOMAIN/APPLICATION/INFRASTRUCTURE/PRESENTATION} - Moved: {function_list} - DTOs introduced: {dto_list or "none"} - No semantic changes - Tests: {test_count} passing ``` ```

```bash php artisan optimize:clear ./vendor/bin/pint {files} php artisan test --filter={relevant_tests} ```

1. **Create new file:** {target_path}/{module_name}.php 2. **Move functions:** {list_of_functions} 3. **Update imports:** Add use statements to original file 4. **Preserve call sites:** Original file calls new location 5. **NO semantic changes:** Pure code movement only

For each identified "mystery meat" structure in this module: 1. Create DTO class: `app/Domain/{Module}/DTOs/{Name}DTO.php` 2. Add typed properties (PHP 8.3 constructor promotion) 3. Replace array usage with DTO

**If target is DOMAIN:** - NO imports of Eloquent models (use interfaces instead) - NO DB queries - NO HTTP calls - NO event firing - PURE PHP — only domain objects, exceptions, value types **If target is APPLICATION:** - MAY orchestrate domain + infrastructure - Handles transactions - Fires events - NO HTTP-specific logic (no Request/Response objects) **If target is INFRASTRUCTURE:** - MAY use Eloquent, DB facade, HTTP client - Implements interfaces defined in Domain - NO business...

{paste from refactor-map}

**Source File:** {original_file} **Target Layer:** {DOMAIN / APPLICATION / INFRASTRUCTURE / PRESENTATION} **Target Directory:** {target_path} **Extraction Order:** {N} of {total}

**For EACH module in extraction order, spawn agent:** **Choose agent:** - Simple extraction → `generic-development` (8x) - Complex state/side-effects → `generic-balanced-thinking` (33x) ```markdown

```bash cat coordination/refactor-maps/{filename}-refactor-map.md ``` **Validate:** - ✅ All modules < 800 lines? (prefer 200-400) - ✅ Layer assignments defined (DOMAIN/APPLICATION/INFRASTRUCTURE)? - ✅ Side-effect inventory complete? - ✅ DTO candidates identified? - ✅ DO-NOT-CHANGE contracts listed? - ✅ ARCHITECTURE.md draft present?

Create: `coordination/refactor-maps/{filename}-refactor-map.md` Include: - Executive summary: current LLM-readability score (A-F) and main blockers - Layer violation map (where domain touches infrastructure) - Side-effect inventory - Mystery meat / DTO candidates - Module boundary diagram (ASCII) with LINE COUNTS and LAYER assignments per module - Naming improvements (top 10 most impactful) - Extraction order (numbered list) - Risk matrix (what could break) - ARCHITECTURE.md draft **MODULE...

Analyze the file(s) with ONE question in mind: **"Can a new LLM understand the domain logic without reading infrastructure code?"** Create a comprehensive LLM Readability Map by identifying: 1. **Layer Violations** - Which functions mix I/O (DB/HTTP/file) with domain logic? - Which functions mix calculation with logging/events? - Where does the domain layer reach into infrastructure? 2. **Side-Effect Inventory** - List every function that: writes to DB, makes HTTP calls, reads...

**Target File(s):** {file_paths} **Total Lines:** {line_count} **Test Coverage:** {coverage_percent}

**Spawn chosen agent with this prompt:** ```markdown

**Count complexity triggers:** - [ ] File > 10,000 lines - [ ] Test coverage < 30% - [ ] Much global state - [ ] Metaprogramming - [ ] Critical code (payment, auth) - [ ] Complex DI - [ ] Event-driven with race conditions **Decision:** - 0-1 triggers → `generic-balanced-thinking` (33x) - 2+ triggers → `generic-heavy` (163x)

**BEFORE any LLM touches the code, ensure:** ```bash # Minimum guardrails (ALL must exist) ✅ Kjørbar build: php artisan optimize:clear && composer dump-autoload ✅ Linting: ./vendor/bin/pint --test (or phpstan) ✅ Test command: php artisan test --filter=ModuleName ✅ Smoke test: curl http://localhost/health OR manual flow check ``` **If test coverage is LOW (< 50%):** ```markdown ⚠️ LOW TEST COVERAGE DETECTED Before refactoring, we MUST create "golden tests": 1. Snapshot current output for...

```bash # MANDATORY before starting git status git diff --name-only wc -l {target_file} ``` **Questions to answer:** 1. What is the file size? (lines, tokens) 2. What test coverage exists? 3. Are there dependent files? 4. Is there global state / singletons? 5. What is the current LLM-readability problem? (Why is this hard to understand?)

**Phase A agent MUST evaluate all large data structures:** | Pattern | File/Code | Database | Why | |---------|-----------|----------|-----| | **Visualization mappings** (50-200 entries) | ✅ Config file | ❌ | Static, versioned with code, grows slowly | | **Analysis rules** (100-500 entries) | ❌ | ✅ Database | User-customizable, frequent updates | | **ECharts templates** (20-50 variants) | ✅ Config file | ❌ | Static, deployed with code | | **Customer settings** (per-customer data) | ❌ | ✅...

**Prefer 200-400 lines over 800 lines:** - 200-400 lines = LLM reads entire file in one pass, builds complete mental model - 400-800 lines = LLM may need to scroll back, loses context - > 800 lines = LLM MUST chunk, loses holistic understanding ---

**Hard rule for Phase A agent:** - No extracted module shall exceed **800 lines** - If a logical grouping is > 800 lines, **split it further** - Target: 200-400 lines per file (LLM sweet spot — fits in one read)

**❌ FORBIDDEN: Creating new giant files** ``` Original: AnalysisOrchestrator.php (11,925 lines) ↓ BAD REFACTORING ↓ DomainLogic.php (9,000 lines) ❌ STILL A MONOLITH! Infrastructure.php (2,900 lines) ✅ OK ```

| Phase | Complexity | Agent | Model | Thinking | Cost | |-------|------------|-------|-------|----------|------| | A | Standard (< 10k lines, > 30% tests) | generic-balanced-thinking | Sonnet | ✅ | 33x | | A | Complex (> 10k OR < 30% tests OR global state) | generic-heavy | Opus | ✅ | 163x | | B | Simple layer separation | generic-development | Sonnet | ❌ | 8x | | B | Complex state / many side-effects | generic-balanced-thinking | Sonnet | ✅ | 33x | | C | Mechanical / DTO introduction |...