characterization-first

name: characterization-first
description: Use when refactoring existing code, modifying legacy code, or about to change code behavior. Use when terms like "characterization test", "golden master", "capture behavior", or "safe refactoring" are mentioned. Enforces discipline of capturing current behavior before any code changes.

The Iron Rule: No refactor without characterization. Period.

Before touching ANY code:
1. Capture what it currently does (including bugs)
2. Verify your characterization is complete
3. Only then make changes

This skill enforces strict discipline. It will block progress until characterization tests exist.

Why this matters: 90% accuracy per step = 59% success over 5 steps. Characterization tests catch unintended behavior changes before they compound into failures.

What characterization tests are NOT:
- They are NOT assertions about correct behavior
- They are NOT contract tests
- They document ACTUAL behavior, bugs and all

Common Excuses - NEVER Fall For These

Red Flags - STOP Immediately

If you're thinking any of these, you're rationalizing:
- "Just this once..."
- "I'll do it properly next time..."
- "The spirit matters more than the letter..."
- "It's just renaming/extracting/simplifying..."

All of these mean: You're about to violate. Don't.

Enforce the discipline of capturing current code behavior as tests before any modification. Produces pytest-based characterization tests that document what code DOES (not what it should do), verifies coverage completeness via mutation testing with mutmut, and only then permits atomic refactoring changes.

Starting a characterization:
1. Tell me what code you want to refactor
2. I'll guide you through SELECT → CAPTURE → VERIFY → REFACTOR phases
3. You cannot skip phases - each gate must pass

Example:

User: I want to refactor execution/utils/validation.py
Skill: Let's characterize it first. Reading the file to identify seams...

What would you like to do?

1. Start new characterization - Begin characterizing code before refactoring
2. Resume characterization - Continue an in-progress characterization
3. Verify coverage - Run mutation testing on existing characterization tests
4. Proceed to refactor - I have characterization tests and want to make changes

Wait for response before proceeding.

| Response | Workflow |
|----------|----------|
| 1, "start", "new", "characterize", "begin" | workflows/select-target.md |
| 2, "resume", "continue" | Ask for target file, then workflows/capture-behavior.md |
| 3, "verify", "coverage", "mutation" | workflows/verify-coverage.md |
| 4, "refactor", "proceed", "ready" | workflows/refactor-safely.md |

After reading the workflow, follow it exactly.

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ SELECT  │ →  │ CAPTURE │ →  │ VERIFY  │ →  │REFACTOR │
│ target  │    │ behavior│    │ coverage│    │ safely  │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
     │              │              │              │
     ▼              ▼              ▼              ▼
  Identify      Write tests     Mutation      Atomic
  seams and     that capture    testing to    changes with
  I/O points    current I/O     find gaps     test after each

Gate Requirements:
- SELECT → CAPTURE: Target identified, seams documented
- CAPTURE → VERIFY: Characterization tests written and passing
- VERIFY → REFACTOR: Mutation testing shows adequate coverage
- REFACTOR complete: All tests still pass, changes committed

All domain knowledge in references/:

Seams: seam-identification.md - Finding testable boundaries
Testing: golden-master-pattern.md - Recording bugs as expected
Coverage: mutation-testing.md - Verifying characterization completeness
TDD Testing: pressure-scenarios.md - Pressure test scenarios for skill validation

| Workflow | Purpose |
|----------|---------|
| select-target.md | Identify code to characterize, find seams |
| capture-behavior.md | Write characterization tests |
| verify-coverage.md | Run mutation testing |
| refactor-safely.md | Make atomic changes with verification |

Deterministic scripts in scripts/ - use these for reliable execution:

Usage pattern:

# SELECT: Analyze target (text report to stdout, or JSON with --json)
python scripts/analyze_target.py path/to/target.py
python scripts/analyze_target.py path/to/target.py --json > .tmp/analysis.json

# CAPTURE: Scaffold tests from target file
python scripts/scaffold_char_tests.py path/to/target.py

# VERIFY: Run mutation testing
./scripts/run_mutation.sh path/to/target.py tests/characterization/test_target_char.py

# VERIFY: Check coverage
python scripts/check_coverage.py --threshold 80

Characterization is complete when:
- [ ] Target code identified with all inputs/outputs documented
- [ ] Characterization tests written and passing
- [ ] Mutation testing shows no surviving mutants (or survivors explicitly accepted)
- [ ] Refactoring changes are atomic (one change, run tests, commit)
- [ ] All characterization tests still pass after refactoring