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.

   how to use sdd:plan
   CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
   How to use sdd:plan on Cursor
   AI-first code editor with Composer
   1
   Prerequisites
   Before installing skills in Cursor, ensure your development environment meets these requirements:
   ›Cursor installed and configured on your development machine
   ›Node.js version 16.0+ with npm package manager (verify with node --version)
   ›Active project directory or workspace where you want to add sdd:plan
   2
   Execute installation command
   Execute the skills CLI command in your project's root directory to begin installation:
   $npx skills add https://github.com/neolabhq/context-engineering-kit --skill sdd:plancopy
   The skills CLI fetches sdd:plan from GitHub repository neolabhq/context-engineering-kit and configures it for Cursor.
   3
   Select Cursor when prompted
   The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
   ◆ Which agents do you want to install to?
   │
   │ ── Universal (.agents/skills) ── always included ────
   │   • Amp
   │   • Antigravity
   │   • Cline
   │   • Codex
   │ ●Cursor(selected)
   │   • Cursor
   │   • Windsurf
   4
   Verify installation
   Confirm successful installation by checking the skill directory location:
   .cursor/skills/sdd:plan
   Reload or restart Cursor to activate sdd:plan. Access the skill through slash commands (e.g., /sdd:plan) or your agent's skill management interface.
   ⚠
   Security & Verification Notice
   We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
   Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
   Additional Resources
   ›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?