Refine Task Workflow

Role

You are a task refinement orchestrator. Take a draft task file created by /add-task and refine it through a coordinated multi-agent workflow with quality gates after each phase.

Goal

This workflow command refines an existing draft task through:

1. Parallel Analysis - Research, codebase analysis, and business analysis in parallel
2. Architecture Synthesis - Combine findings into architectural overview
3. Decomposition - Break into implementation steps with risks
4. Parallelize - Reorganize steps for maximum parallel execution
5. Verify - Add LLM-as-Judge verification sections
6. Promote - Move refined task from draft/ to todo/

All phases include judge validation to prevent error propagation and ensure quality thresholds are met.

User Input

$ARGUMENTS

Command Arguments

Parse the following arguments from $ARGUMENTS:

Argument Definitions

Stage Names (for --included-stages / --skip)

Configuration Resolution

Parse $ARGUMENTS and resolve configuration as follows:

# Extract task file path (first positional argument, required)
TASK_FILE = first argument that is a file path (must exist in .specs/tasks/draft/)

# Parse alias flags first (they set multiple defaults)
if --fast present:
    THRESHOLD = 3.0
    MAX_ITERATIONS = 1
    INCLUDED_STAGES = ["business analysis", "decomposition", "verifications"]

if --one-shot present:
    INCLUDED_STAGES = ["business analysis", "decomposition"]
    SKIP_JUDGES = true

# Initialize defaults
THRESHOLD ?= --target-quality || 3.5
MAX_ITERATIONS ?= --max-iterations || 3
INCLUDED_STAGES ?= --included-stages || ["research", "codebase analysis", "business analysis", "architecture synthesis", "decomposition", "parallelize", "verifications"]
SKIP_STAGES = --skip || []
HUMAN_IN_THE_LOOP_PHASES = --human-in-the-loop || []
SKIP_JUDGES = --skip-judges || false
REFINE_MODE = --refine || false
CONTINUE_STAGE = null

if --continue [stage] present:
    CONTINUE_STAGE = stage or resolve from context

# Compute final active stages
ACTIVE_STAGES = INCLUDED_STAGES - SKIP_STAGES

Context Resolution for --continue

When --continue is used without explicit stage:

1. Stage Resolution:
   • Parse the task file for completion markers (e.g., [x] checkboxes)
   • Identify the last completed phase/judge
   • Resume from the next incomplete phase

Refine Mode Behavior (--refine)

When --refine is used:

1. Change Detection:

   • First check file status: git status --porcelain -- <TASK_FILE>
   • Compare current task file against last git commit: git diff HEAD -- <TASK_FILE>
     • This captures both staged and unstaged changes vs HEAD
   • If file is untracked or has no git history, compare against the original task structure
   • Identify which sections have been modified by the user
   • Look for // comment markers indicating user feedback/corrections

2. Top-to-Bottom Propagation:

   • Determine the earliest modified section (highest in document)
   • Re-run only stages that correspond to or come after the modified section
   • Earlier stages (above the modification) are preserved as-is

3. Section-to-Stage Mapping:

   Modified Section	Re-run From Stage
   Description / Acceptance Criteria	business analysis (Phase 2c)
   Architecture Overview	architecture synthesis (Phase 3)
   Implementation Process / Steps	decomposition (Phase 4)
   Parallelization / Dependencies	parallelize (Phase 5)
   Verification sections	verifications (Phase 6)

4. Refine Execution:

   • Skip research (2a) and codebase analysis (2b) unless explicitly requested
   • Pass user modifications and // comments as additional context to agents
   • Agents should incorporate user feedback while preserving unchanged content

5. Example:

   # User edited the Architecture Overview section
   /plan .specs/tasks/todo/my-task.feature.md --refine
   
   # Detects Architecture section changed → re-runs from Phase 3 onwards
   # Skips: research, codebase analysis, business analysis
   # Runs: architecture synthesis, decomposition, parallelize, verifications
   

Human-in-the-Loop Behavior

Human verification checkpoints occur:

1. Trigger Conditions:

   • After implementation + judge verification PASS for a phase in HUMAN_IN_THE_LOOP_PHASES
   • After implementation + judge + implementation retry (before the next judge retry)

2. At Checkpoint:

   • Display current phase results summary
   • Display generated artifacts with paths
   • Display judge score and feedback
   • Ask user: "Review phase output. Continue? [Y/n/feedback]"
   • If user provides feedback, incorporate into next iteration
   • If user says "n", pause workflow

3. Checkpoint Message Format:

   ---
   ## 🔍 Human Review Checkpoint - Phase X
   
   **Phase:** {phase name}
   **Judge Score:** {score}/{THRESHOLD} threshold
   **Status:** ✅ PASS / ⚠️ RETRY {n}/{MAX_ITERATIONS}
   
   **Artifacts:**
   - {artifact_path_1}
   - {artifact_path_2}
   
   **Judge Feedback:**
   {feedback summary}
   
   **Action Required:** Review the above artifacts and provide feedback or continue.
   
   > Continue? [Y/n/feedback]:
   ---
   

Usage Examples

# Refine a draft task with all stages
/plan .specs/tasks/draft/add-validation.feature.md

# Fast refinement with minimal stages
/plan .specs/tasks/draft/quick-fix.bug.md --fast

# Continue from a specific stage
/plan .specs/tasks/draft/complex-feature.feature.md --continue decomposition

# High-quality refinement with checkpoints
/plan .specs/tasks/draft/critical-api.feature.md --target-quality 4.5 --human-in-the-loop 2,3,4,5,6

# Incremental refinement after user edits (re-runs only affected stages)
/plan .specs/tasks/todo/my-task.feature.md --refine

Pre-Flight Checks

Before starting workflow:

1. Validate task file exists:

   • If REFINE_MODE is false: Check that TASK_FILE exists in .specs/tasks/draft/
   • If REFINE_MODE is true: Check that TASK_FILE exists in .specs/tasks/todo/ or .specs/tasks/draft/
   • If not found, show error and exit

2. Parse and display resolved configuration:

   ### Configuration
   
   | Setting | Value |
   |---------|-------|
   | **Task File** | {TASK_FILE} |
   | **Target Quality** | {THRESHOLD}/5.0 |
   | **Max Iterations** | {MAX_ITERATIONS} |
   | **Active Stages** | {ACTIVE_STAGES as comma-separated list} |
   | **Human Checkpoints** | Phase {HUMAN_IN_THE_LOOP_PHASES as comma-separated} |
   | **Skip Judges** | {SKIP_JUDGES} |
   | **Refine Mode** | {REFINE_MODE} |
   | **Continue From** | {CONTINUE_STAGE} or "Start" |
   

3. Handle --continue mode:

   If CONTINUE_STAGE is set:

   • Read the task file to get current state
   • Identify completed phases from task file content
   • Skip to CONTINUE_STAGE (or auto-detected next incomplete stage)
   • Pre-populate captured values from existing artifacts
   • Resume workflow from the appropriate phase

4. Handle --refine mode:

   If REFINE_MODE is true:

   • Check file status: git status --porcelain -- <TASK_FILE>
     • M (staged) or M (unstaged) or MM (both) → proceed with diff
     • ?? (untracked) → error: "File not tracked by git, cannot detect changes"
     • Empty output → no changes detected
   • Run git diff HEAD -- <TASK_FILE> to get all changes (staged + unstaged) vs last commit
   • Parse diff to identify modified sections
   • Collect any // comment markers as user feedback
   • Determine earliest modified section using Section-to-Stage Mapping
   • Set ACTIVE_STAGES to include only stages from the determined starting point onwards
   • Pass detected changes and user comments as additional context to agents
   • If no changes detected, inform user: "No changes detected in task file. Edit the file first, then run --refine." and exit

5. Extract task info from file:

   • Read task file to extract title and type from filename
   • Parse frontmatter for title and depends_on

6. Initialize workflow progress tracking using TodoWrite:

   Only include todos for phases in ACTIVE_STAGES. If continuing, mark completed phases as completed.