/typed-holes-refactor

name: typed-holes-refactor
description: Refactor codebases using Design by Typed Holes methodology - iterative, test-driven refactoring with formal hole resolution, constraint propagation, and continuous validation. Use when refactoring existing code, optimizing architecture, or consolidating technical debt through systematic hole-driven development.

Typed Holes Refactoring

Systematically refactor codebases using the Design by Typed Holes meta-framework: treat architectural unknowns as typed holes, resolve them iteratively with test-driven validation, and propagate constraints through dependency graphs.

Core Workflow

Phase 0: Hole Discovery & Setup

**1. Create safe working branch:**

git checkout -b refactor/typed-holes-v1
# CRITICAL: Never work in main, never touch .beads/ in main

**2. Analyze current state and identify holes:**

python scripts/discover_holes.py
# Creates REFACTOR_IR.md with hole catalog

The Refactor IR documents:

• **Current State Holes**: What's unknown about the current system?
• **Refactor Holes**: What needs resolution to reach the ideal state?
• **Constraints**: What must be preserved/improved/maintained?
• **Dependencies**: Which holes block which others?

**3. Write baseline characterization tests:**

Create `tests/characterization/` to capture exact current behavior:

# tests/characterization/test_current_behavior.py
def test_api_contracts():
    """All public APIs must behave identically post-refactor"""
    for endpoint in discover_public_apis():
        old_result = run_current(endpoint, test_inputs)
        save_baseline(endpoint, old_result)

def test_performance_baselines():
    """Record current performance - don't regress"""
    baselines = measure_all_operations()
    save_json("baselines.json", baselines)

Run tests on main branch - they should all pass. These are your safety net.

Phase 1-N: Iterative Hole Resolution

For each hole (in dependency order):

**1. Select next ready hole:**

python scripts/next_hole.py
# Shows holes whose dependencies are resolved

**2. Write validation tests FIRST (test-driven):**

# tests/refactor/test_h{N}_resolution.py
def test_h{N}_resolved():
    """Define what 'resolved correctly' means"""
    # This should FAIL initially
    assert desired_state_achieved()

def test_h{N}_equivalence():
    """Ensure no behavioral regressions"""
    old_behavior = load_baseline()
    new_behavior = run_refactored()
    assert old_behavior == new_behavior

**3. Implement resolution:**

• Refactor code to make tests pass
• Keep characterization tests passing
• Commit incrementally with clear messages

**4. Validate resolution:**

python scripts/validate_resolution.py H{N}
# Checks: tests pass, constraints satisfied, main untouched

**5. Propagate constraints:**

python scripts/propagate.py H{N}
# Updates dependent holes based on resolution

**6. Document and commit:**

git add .
git commit -m "Resolve H{N}: {description}

- Tests: tests/refactor/test_h{N}_*.py pass
- Constraints: {constraints satisfied}
- Propagates to: {dependent holes}"

Phase Final: Reporting

**Generate comprehensive delta report:**

python scripts/generate_report.py > REFACTOR_REPORT.md

Report includes:

• Hole resolution summary with validation evidence
• Metrics delta (LOC, complexity, coverage, performance)
• Behavioral analysis (intentional changes documented)
• Constraint validation (all satisfied)
• Risk assessment and migration guide

Key Principles

1. Test-Driven Everything

• Write validation criteria BEFORE implementing
• Tests define "correct resolution"
• Characterization tests are sacred - never let them fail

2. Hole-Driven Progress

• Resolve holes in dependency order
• Each resolution propagates constraints
• Track everything formally in Refactor IR

3. Continuous Validation

Every commit must validate:

• ✅ Characterization tests pass (behavior preserved)
• ✅ Resolution tests pass (hole resolved correctly)
• ✅ Constraints satisfied
• ✅ Main branch untouched
• ✅ `.beads/` intact in main

4. Safe by Construction

• Work only in refactor branch
• Main is read-only reference
• Beads are untouchable historical artifacts

5. Formal Completeness

Design complete when:

• All holes resolved and validated
• All constraints satisfied
• All phase gates passed
• Metrics improved or maintained

Hole Quality Framework

SMART Criteria for Good Holes

Every hole must be:

• **Specific**: Clear, bounded question with concrete answer
• ✓ Good: "How should error handling work in the API layer?"
• ✗ Bad: "How to improve the code?"

• **Measurable**: Has testable validation criteria
• ✓ Good: "Reduce duplication from 60% to <15%"
• ✗ Bad: "Make code better"

• **Achievable**: Can be resolved with available information
• ✓ Good: "Extract parsing logic to separate module"
• ✗ Bad: "Predict all future requirements"

• **Relevant**: Blocks meaningful progress on refactoring
• ✓ Good: "Define core interface (blocks 5 other holes)"
• ✗ Bad: "Decide variable naming convention"

• **Typed**: Clear type/structure for resolution
• ✓ Good: `interface Architecture = { layers: Layer[], rules: Rule[] }`
• ✗ Bad: "Some kind of structure?"

Hole Estimation Framework

Size holes using these categories:

| Size | Duration | Characteristics | Examples | |------|----------|-----------------|----------| | **Nano** | 1-2 hours | Simple, mechanical changes | Rename files, update imports | | **Small** | 4-8 hours | Single module refactor | Extract class, consolidate functions | | **Medium** | 1-3 days | Cross-module changes | Define interfaces, reorganize packages | | **Large** | 4-7 days | Architecture changes | Layer extraction, pattern implementation | | **Epic** | >7 days | **SPLIT THIS HOLE** | Too large, break into smaller holes |

**Estimation Red Flags**:

• More than 3 dependencies → Like