Refine

---
allowed-tools:
  - Bash
  - Read
  - Task
  - Edit
  - Write
  - Glob
  - Grep
description: "Usage: /iris:refine - Run Ralph-style iterative refinement loop"
---

# Iris Refine Module

**Purpose:** Implement Ralph Wiggum-style iterative refinement to improve the implementation toward better PRD alignment.

**Can be invoked:**
- **Standalone:** `/iris:refine` - Run refinement on an existing project
- **Via Autopilot:** Executed inline as part of `/iris:autopilot` workflow

---

## Initialization (Standalone or Inline)

**First, establish the environment variables if not already set:**

```bash
# Find project root if not set (standalone invocation)
if [[ -z "$PROJECT_ROOT" ]]; then
    PROJECT_ROOT=$(pwd)
    while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.claude" ]]; do
        PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
    done
fi

# Find IRIS directory if not set
if [[ -z "$IRIS_DIR" ]]; then
    if [[ -d "$PROJECT_ROOT/.claude/commands/iris" ]]; then
        IRIS_DIR="$PROJECT_ROOT/.claude/commands/iris"
    elif [[ -d "$HOME/.claude/commands/iris" ]]; then
        IRIS_DIR="$HOME/.claude/commands/iris"
    fi
fi

# Set environment variable for DatabaseManager
export IRIS_PROJECT_ROOT="$PROJECT_ROOT"

echo "🔄 IRIS Refine Module"
echo "   Project Root: $PROJECT_ROOT"
echo "   IRIS Directory: $IRIS_DIR"
echo ""

# Verify project has been planned (tasks exist)
TASK_CHECK=$(python3 -c "
import sys
sys.path.insert(0, '$IRIS_DIR/utils')
from database.db_manager import DatabaseManager

try:
    db = DatabaseManager('$PROJECT_ROOT')
    with db.get_connection() as conn:
        tasks = conn.execute('SELECT COUNT(*) as c FROM tasks').fetchone()['c']
        completed = conn.execute(\"SELECT COUNT(*) as c FROM tasks WHERE status = 'completed'\").fetchone()['c']
        print(f'{tasks}:{completed}')
except Exception as e:
    print(f'error:{e}')
")

IFS=':' read -r TOTAL_TASKS COMPLETED_TASKS <<< "$TASK_CHECK"

if [[ "$TOTAL_TASKS" == "error"* ]]; then
    echo "❌ ERROR: Cannot access project database"
    echo "   $TASK_CHECK"
    echo "   Run /iris:plan first to initialize the project."
    exit 1
fi

if [[ "$TOTAL_TASKS" -eq 0 ]]; then
    echo "❌ ERROR: No tasks found in project"
    echo "   Run /iris:plan first to create tasks."
    exit 1
fi

echo "📊 Project Status: $COMPLETED_TASKS/$TOTAL_TASKS tasks completed"
echo ""

---

Prose-Orchestration Context

When invoked via autopilot (inline execution), this module:

1. Has access to the PRD - Stored in project_metadata, retrieve it for each refiner iteration
2. Has access to $IRIS_DIR - Set by autopilot.md or initialization above
3. Has access to $PROJECT_ROOT - Set by autopilot.md or initialization above
4. Returns control to autopilot.md - After completing all iterations

---

Ralph Wiggum Philosophy

This module implements the Ralph Wiggum iterative refinement approach:

Principle	Implementation
Fresh Context	Each iteration uses fresh subagents that see the codebase without accumulated baggage
Progress in Files	Improvements are committed to git; state persists in database
Fixed Iterations	Loop runs exactly max_iterations times — do NOT terminate early
Improve, Not Just Fix	Focus on enhancement toward PRD intent, not just bug repair
PRD Anchoring	Refiner receives the original PRD each iteration to maintain alignment
Backpressure	Validation provides feedback but doesn't terminate the loop

Critical: The loop MUST run for the full max_iterations count. Do not exit early even if no issues are found. Each iteration provides fresh perspective for improvement.

---

Configuration by Complexity

Retrieve refine configuration based on project complexity:

Complexity	Max Iterations	Reviewers	Review Focus Areas
MICRO	5	2	gaps, quality
SMALL	5	3	gaps, quality, edge_cases
MEDIUM	6	4	gaps, quality, integration, edge_cases
LARGE	8	5	gaps, quality, integration, edge_cases, security
ENTERPRISE	10	6	gaps, quality, integration, edge_cases, security, performance

---

Phase 0: Initialization

Step 0.1: Load Configuration

# Get refine configuration from database
python3 -c "
import sys
sys.path.append('$IRIS_DIR/utils')
from database.db_manager import DatabaseManager

db = DatabaseManager()
with db.get_connection() as conn:
    # Get complexity
    result = conn.execute('''
        SELECT value FROM project_metadata WHERE key = 'project_complexity'
    ''').fetchone()
    complexity = result['value'] if result else 'MEDIUM'

    # Get max iterations (default based on complexity)
    iter_result = conn.execute('''
        SELECT value FROM project_state WHERE key = 'refine_max_iterations'
    ''').fetchone()

    # Complexity-based defaults
    defaults = {
        'MICRO': 5, 'SMALL': 5, 'MEDIUM': 6,
        'LARGE': 8, 'ENTERPRISE': 10
    }
    max_iter = int(iter_result['value']) if iter_result else defaults.get(complexity.upper(), 5)

    print(f'COMPLEXITY: {complexity}')
    print(f'MAX_ITERATIONS: {max_iter}')
"

Store the values:

• $COMPLEXITY = detected complexity level
• $MAX_ITERATIONS = number of iterations to run (minimum 5)

Step 0.2: Load PRD Content

# Retrieve PRD from database
python3 -c "
import sys
sys.path.append('$IRIS_DIR/utils')
from database.db_manager import DatabaseManager

db = DatabaseManager()
with db.get_connection() as conn:
    result = conn.execute('''
        SELECT value FROM project_metadata WHERE key = 'prd_content'
    ''').fetchone()
    if result:
        print(result['value'])
    else:
        print('ERROR: PRD not found in database')
"

Store as $PRD_CONTENT for use in refiner prompts.

Step 0.3: Load Tech Stack

# Get approved tech stack
python3 -c "
import sys
import json
sys.path.append('$I