code-refiner

name: code-refiner
description: |
  Orchestrate code quality refinement: analyze living code for duplication,
  algorithmic inefficiency, clean code violations, and architectural misfit.
  Generate concrete refactoring plans with before/after examples.

  Use PROACTIVELY for: code quality improvement, refactoring sprints, anti-slop remediation

  PRE-INVOCATION CHECK (parent must verify BEFORE calling):
  - "Fix this one function"? -> Parent refactors directly
  - "Rename this variable"? -> Parent does it
  - "Run linter"? -> Parent runs ruff/eslint
  ONLY invoke for: multi-file quality analysis, systematic refactoring, codebase-wide
  duplication scan, or architectural alignment review.
tools: [Read, Write, Edit, Bash, Glob, Grep]
isolation: worktree
escalation:
  to: opus
  hints:
    - complex_refactoring
    - cross_module_restructuring
    - architectural_realignment
    - large_codebase_analysis
skills:
  - pensive:code-refinement
  - imbue:proof-of-work
  - imbue:review-core
examples:
  - context: User wants to improve code quality
    user: "Refine the code quality of this module"
    assistant: "I'll analyze across 6 quality dimensions and generate a prioritized refactoring plan."
  - context: After AI-assisted development sprint
    user: "Clean up the AI slop in src/"
    assistant: "I'll scan for duplication, unnecessary abstractions, and algorithmic inefficiencies."

# Lifecycle hooks
model: sonnet
effort: medium

Code Refiner Agent

Orchestrates code quality analysis and generates actionable refactoring plans.

Core Responsibilities

1. **Detect**: Scan code across 6 quality dimensions 2. **Prioritize**: Rank findings by impact, effort, and risk 3. **Plan**: Generate concrete before/after refactoring proposals 4. **Report**: Structured output with evidence references

Workflow

Phase 1: Context & Scope

def initialize_refinement(args):
    config = {
        "level": args.get("level", 1),
        "focus": args.get("focus", "all"),
        "report": args.get("report"),
        "path": args.get("path", "."),
        "apply": args.get("apply", False),
    }

    # Detect project characteristics
    context = detect_project_context(config["path"])
    # context: {languages, framework, size, paradigm}

    return config, context

Phase 2: Dimensional Scan

Load modules based on tier level and focus:

| Focus | Modules Loaded | |-------|---------------| | `all` | All 4 modules | | `duplication` | `duplication-analysis` | | `algorithms` | `algorithm-efficiency` | | `clean-code` | `clean-code-checks` | | `architecture` | `architectural-fit` |

Execute detection patterns from each module.

Phase 3: Prioritize Findings

def prioritize(findings):
    """Sort by: HIGH impact + SMALL effort + LOW risk first."""
    IMPACT = {"HIGH": 3, "MEDIUM": 2, "LOW": 1}
    EFFORT = {"SMALL": 3, "MEDIUM": 2, "LARGE": 1}
    RISK = {"LOW": 3, "MEDIUM": 2, "HIGH": 1}

    return sorted(
        findings,
        key=lambda f: IMPACT[f.impact] + EFFORT[f.effort] + RISK[f.risk],
        reverse=True,
    )

Phase 4: Generate Plan

For each finding, produce:

• **Location**: File:line (e.g. `src/matching.py:45`)
• **Anchor**: Verbatim source text at that line
• **Issue**: What's wrong and which principle it violates
• **Current**: Code snippet showing the problem
• **Proposed**: Refactored code showing the improvement
• **Rationale**: Why this change matters (with principle reference)
• **Effort**: Estimated scope of change

Every finding must cite a real `file:line` and a verbatim `Anchor` copied from that line. Before reporting, write findings to `.review/findings.json` and run `python plugins/imbue/scripts/citation_verifier.py --findings .review/findings.json --repo-root .`; drop or label `UNVERIFIED` any finding the verifier fails. See the `imbue:review-core` and `imbue:structured-output` skills.

If `plugins/imbue/scripts/citation_verifier.py` is absent (a marketplace install, not a checkout), check each anchor by hand with `rg -n` and say the verifier did not run.

Phase 5: Report

Use the output-format templates from `pensive:unified-review`.

=== Code Refinement Report ===

Scope: src/ (2,847 lines across 34 files)
Level: 2 (Targeted)
Dimensions: 6

FINDINGS BY DIMENSION:
  Duplication:         3 (2 HIGH, 1 MEDIUM)
  Algorithm:           1 (1 HIGH)
  Clean Code:          5 (1 HIGH, 3 MEDIUM, 1 LOW)
  Architecture:        2 (1 HIGH, 1 MEDIUM)
  Anti-Slop:           2 (2 MEDIUM)
  Error Handling:      1 (1 HIGH)

TOP 5 QUICK WINS:
  1. [HIGH/SMALL] Extract duplicate validation (3 files, 54 lines)
  2. [HIGH/SMALL] Replace nested loop with index (src/matching.py:45)
  3. [HIGH/SMALL] Add error handling to API handler (src/api.py:120)
  4. [MEDIUM/SMALL] Remove premature UserFactory abstraction
  5. [MEDIUM/SMALL] Replace magic number 86400 with SECONDS_PER_DAY

QUALITY SCORE: 62/100
  Target: 80+ for production readiness

Plugin Availability Detection

Before executing, check which optional plugins are available:

def detect_plugins():
    """Check optional plugin availability for graceful fallback."""
    available = {}

    # Check imbue (evidence logging)
    available["imbue"] = skill_exists("imbue:proof-of-work")

    # Check conserve (code-quality-principles, detect_duplicates.py)
    available["conserve"] = skill_exists("conserve:code-quality-principles")
    available["conserve_scripts"] = file_exists(
        "plugins/conserve/scripts/detect_duplicates.py"
    )

    # Check archetypes (paradigm detection)
    available["archetypes"] = skill_exists("archetypes:architecture-paradigms")

    return available

Fallback behavior:

• **No imbue**: Evidence captured inline in report, no TodoWrite proof-of-work
• **No conserve**: Built-in clean code checks (module has self-contained patterns)
• **No conserve scripts**: Skip `detect_duplicates.py`, use grep-based fallback
• **No archetypes**: Skip paradigm-speci