typed-holes-refactor

What this skill does

# 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:**

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

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

```bash
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:

```python
# 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:**

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

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

```python
# 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:**

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

**5. Propagate constraints:**

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

**6. Document and commit:**

```bash
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:**

```bash
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 → Likely Medium+
- Unclear validation → Add time for discovery
- New patterns/tools → Add learning overhead

### Hole Splitting Guidelines

**Split a hole when**:
1. Estimate exceeds 7 days
2. More than 5 dependencies
3. Validation criteria unclear
4. Multiple distinct concerns mixed

**Splitting strategy**:
```
Epic hole: "Refactor entire authentication system"
→ Split into:
  R10_auth_interface: Define new auth interface (Medium)
  R11_token_handling: Implement JWT tokens (Small)
  R12_session_management: Refactor sessions (Medium)
  R13_auth_middleware: Update middleware (Small)
  R14_auth_testing: Comprehensive test suite (Medium)
```

**After splitting**:
- Update dependencies in REFACTOR_IR.md
- Run `python scripts/propagate.py` to update graph
- Re-sync with beads: `python scripts/holes_to_beads.py`

## Common Hole Types

### Architecture Holes

```python
"?R1_target_architecture": "What should the ideal structure be?"
"?R2_module_boundaries": "How should modules be organized?"
"?R3_abstraction_layers": "What layers/interfaces are needed?"
```

**Validation:** Architecture tests, dependency analysis, layer violation checks

### Implementation Holes

```python
"?R4_consolidation_targets": "What code should merge?"
"?R5_extraction_targets": "What code should split out?"
"?R6_elimination_targets": "What code should be removed?"
```

**Validation:** Duplication detection, equivalence tests, dead code analysis

### Quality Holes

```python
"?R7_test_strategy": "How to validate equivalence?"
"?R8_migration_path": "How to safely transition?"
"?R9_rollback_mechanism": "How to undo if needed?"
```

**Validation:** Test coverage metrics, migration dry-runs, rollback tests

See [HOLE_TYPES.md](references/HOLE_TYPES.md) for complete catalog.

## Constraint Propagation Rules

### Rule 1: Interface Resolution → Type Constraints

```
When: Interface hole resolved with concrete types
Then: Propagate type requirements to all consumers

Example:
  Resolve R6: NodeInterface = BaseNode with async run()
  Propagates to:
    → R4: Parallel execution must handle async
    → R5: Error recovery must handle async exceptions
```

### Rule 2: Implementation → Performance Constraints

```
When: Implementation resolved with resource usage
Then: Propagate limits to dependent holes

Example:
  Resolve R4: Parallelization with max_concurrent=3
  Propa