sdd:plan

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

| Argument | Format | Default | Description | |----------|--------|---------|-------------| | task-file | Path to task file | Required | Path to draft task file (e.g., .specs/tasks/draft/add-validation.feature.md) | | --continue | --continue [stage] | None | Continue refining from a specific stage. Stage is optional - resolve from context if not provided. | | --target-quality | --target-quality X.X | 3.5 | Target threshold value (out of 5.0) for judge pass/fail decisions. | | --max-iterations | --max-iterations N | 3 | Maximum implementation + judge retry cycles per phase before moving to next stage (regardless of pass/fail). | | --included-stages | --included-stages stage1,stage2,... | All stages | Comma-separated list of stages to include. | | --skip | --skip stage1,stage2,... | None | Comma-separated list of stages to exclude. | | --fast | --fast | N/A | Alias for --target-quality 3.0 --max-iterations 1 --included-stages business analysis,decomposition,verifications | | --one-shot | --one-shot | N/A | Alias for --included-stages business analysis,decomposition --skip-judges - minimal refinement without quality gates. | | --human-in-the-loop | --human-in-the-loop phase1,phase2,... | None | Phases after which to pause for human verification. | | --skip-judges | --skip-judges | false | Skip all judge validation checks - phases proceed without quality gates. | | --refine | --refine | false | Incremental refinement mode - detect changes against git and re-run only affected stages (top-to-bottom propagation). |

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

| Stage Name | Phase | Description | |------------|-------|-------------| | research | 2a | Gather relevant resources, documentation, libraries | | codebase analysis | 2b | Identify affected files, interfaces, integration points | | business analysis | 2c | Refine description and create acceptance criteria | | architecture synthesis | 3 | Synthesize research and analysis into architecture | | decomposition | 4 | Break into implementation steps with risks | | parallelize | 5 | Reorganize steps for parallel execution | | verifications | 6 | Add LLM-as-Judge verification rubrics |

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:
2. Parse the task file for completion markers (e.g., [x] checkboxes)
3. Identify the last completed phase/judge
4. Resume from the next incomplete phase

Refine Mode Behavior (--refine)

When --refine is used:

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

1. Top-to-Bottom Propagation:
2. Determine the earliest modified section (highest in document)
3. Re-run only stages that correspond to or come after the modified section
4. Earlier stages (above the modification) are preserved as-is

1. 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) |

1. Refine Execution:
2. Skip research (2a) and codebase analysis (2b) unless explicitly requested
3. Pass user modifications and // comments as additional context to agents
4. Agents should incorporate user feedback while preserving unchanged content

1. Example:

```bash # 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:
2. After implementation + judge verification PASS for a phase in HUMAN_IN_THE_LOOP_PHASES
3. After implementation + judge + implementation retry (before the next judge retry)

1. At Checkpoint:
2. Display current phase results summary
3. Display generated artifacts with paths
4. Display judge score and feedback
5. Ask user: "Review phase output. Continue? [Y/n/feedback]"
6. If user provides feedback, incorporate into next iteration
7. If user says "n", pause workflow

1. Checkpoint Message Format:

```markdown

## 🔍 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-