tdd-refactor-review

name	tdd-refactor-review
title	TDD Refactor Review Skill
description	Guides an independent, read-only code review of refactor-only diffs after the GREEN commit and before REFACTOR verification. Blocks cycle completion when material findings remain.
role	phase-skill
user-invocable	false
contracts	["refactor_review_request","refactor_review_result"]

TDD Refactor Review Skill

Purpose

• Review the REFACTOR diff against the committed GREEN baseline
• Preserve behavior while improving design quality
• Catch refactor scope creep, weakened tests, inconsistent abstractions, and readability regressions
• Decide whether the cycle can proceed to tdd-test-run

Inputs

• Scenario slice
• GREEN commit SHA and message
• Files changed during REFACTOR
• Refactor diff from the GREEN commit baseline
• Project refactor patterns from .github/skills/tdd-refactor/assets/project-refactor-patterns.md
• Surrounding-code rule from .github/skills/tdd-refactor/assets/surrounding-code-review.md

Outputs

• Review verdict
• Blocking findings with file and line references
• Non-blocking suggestions, if useful
• Required next action

Steps

1. Load .github/skills/tdd-refactor/assets/project-refactor-patterns.md.
2. Load .github/skills/tdd-refactor/assets/surrounding-code-review.md.
3. Inspect only the diff from the GREEN commit baseline to the current working tree.
4. Read surrounding functions, tests, or modules for each changed area before making consistency findings.
5. Report status: changes_requested for any material finding.
6. Report status: approved only when no material findings remain.
7. Report status: escalate when the diff cannot be reviewed safely, the baseline is unclear, or files changed outside the declared refactor scope.

Blocking Finding Criteria

• Likely behavior change, deleted behavior, or changed error/edge-case semantics
• Test weakened, removed, made non-deterministic, or made less clear about the protected behavior
• Refactor introduces confusing naming, coupling, hidden side effects, or abstraction that conflicts with nearby code
• Refactor leaves touched code materially harder to read or maintain
• Refactor includes new behavior, unrelated formatting churn, broad rewrites, or other scope creep

Non-Blocking Finding Criteria

• Small naming preference with no readability risk
• Optional simplification that can wait for a later cycle
• Formatting or import-order issue better handled by project tooling

Result Contract Rules

• approved advances to REFACTOR verification through tdd-test-run.
• changes_requested returns to tdd-refactor for scoped fixes, then requires another review.
• escalate stops the cycle and returns escalate_cycle_failure.
• The reviewer never edits files, stages changes, commits, reformats, or reverts.

Output Format

Return refactor_review_result with:

{
  "contract": "refactor_review_result",
  "from": "tdd-refactor-reviewer",
  "to": "cycle_runner",
  "status": "approved | changes_requested | escalate",
  "findings": [
    {
      "severity": "blocking | suggestion",
      "file": "path/to/file",
      "line": 42,
      "title": "Short finding title",
      "details": "Why this matters for behavior preservation or maintainability"
    }
  ],
  "nextAction": "test_run_request | refactor_request | escalate_cycle_failure",
  "notes": ["optional"]
}

Completion Checks

• The review is based on the refactor-only diff from the GREEN commit.
• Nearby code was inspected for changed areas.
• Material findings block the cycle.
• Approval does not replace REFACTOR test verification.