Iterative Refinement Workflow

⚠️ RETIRED 2026-07-09 — the /task-refine command was removed (docs/decisions/DEC-task-refine-retirement.md). To iterate on review feedback, re-run /task-work TASK-XXX; for review findings, use /task-review's [I]mplement flow. This document is preserved as a historical record of the workflow it described.

For current commands and installation cleanup, use the July modernisation and migration guide. The examples below describe the retired workflow and are not runnable current guidance.

Overview

The /task-refine command enables lightweight, iterative improvements to completed tasks without triggering the full /task-work workflow. Use this for minor code quality improvements, clarifications, and polish after a task passes quality gates.

Key Benefits: - Context Preservation: Retains original implementation plan, review comments, audit history - Lightweight Process: Skips planning and architectural review phases - Multiple Iterations: Apply refinements in small, focused cycles - Safe Modifications: Maintains all quality gates (tests must still pass)

Not a Replacement For: Major refactoring, new features, architectural changes, or bug fixes requiring significant rework. Use /task-work for those.

Prerequisites

Task State Requirements: - Task must be in in_review or completed state - All tests must currently be passing (100% pass rate) - Implementation must be complete (not in in_progress or blocked)

What You'll Need: - Clear refinement goal (specific, focused change) - Understanding of existing implementation - Confidence that change won't break tests

When to Refine vs Re-work

✅ Use /task-refine When:

Code Quality Improvements: - Variable/function renaming for clarity - Adding inline comments or docstrings - Extracting helper functions (no logic change) - Improving formatting or style - Adding type hints or annotations

Small Additions: - Adding logging statements - Adding defensive checks (validation, null checks) - Improving error messages - Adding debug information

Minor Adjustments: - Adjusting default values - Changing log levels - Tweaking timeouts or thresholds - Fixing typos in strings or comments

❌ Use /task-work (Full Re-work) When:

New Features: - Adding functionality not in original scope - Implementing new requirements - Extending API surface area - New file creation required

Architectural Changes: - Changing design patterns - Refactoring class structure - Modifying data flow - Changing dependencies

Major Refactoring: - Moving code between modules - Splitting or merging classes - Changing interfaces or contracts - Deleting significant code

Bug Fixes: - Fixing logic errors - Correcting algorithm flaws - Resolving race conditions - Addressing security vulnerabilities

Decision Tree

Need to modify completed task?
│
├─ Changes affect behavior? ──────────────────────────→ YES → Use /task-work
│
├─ Changes add new features? ─────────────────────────→ YES → Use /task-work
│
├─ Changes require new files? ────────────────────────→ YES → Use /task-work
│
├─ Changes may break tests? ──────────────────────────→ YES → Use /task-work
│
├─ Changes are architectural? ────────────────────────→ YES → Use /task-work
│
└─ Small quality improvements only? ──────────────────→ YES → Use /task-refine
   (naming, comments, formatting, logging)

Context Preservation Benefits

What Gets Preserved

1. Implementation Plan - Original plan remains intact - Refinement notes added as appendix - Plan version history maintained

2. Architectural Review Results - Original scores preserved (SOLID, DRY, YAGNI) - Refinement doesn't trigger re-review - Historical review comments retained

3. Plan Audit History - Original variance analysis preserved - Refinement tracked as separate change - Cumulative refinement log maintained

4. Test Results - Original test results archived - New test results added to history - Coverage changes tracked

Why This Matters

Traceability: - Can trace decision history (why was it built this way?) - Audit trail for compliance (what changed when?) - Learning resource (how did design evolve?)

Efficiency: - No need to re-generate implementation plan - No architectural review overhead - Fast iteration (2-5 minutes vs 15-20 minutes)

Safety: - Original context prevents over-refinement - Helps decide when to stop refining - Catches scope creep in refinements

Command Usage

Basic Syntax

/task-refine TASK-XXX "refinement description"

Parameters: - TASK-XXX: Task ID (must be in in_review or completed state) - "refinement description": Brief description of change (1-2 sentences)

Flags: - --dry-run: Preview changes without applying (coming soon)

Note: For epic/feature hierarchy and context, see RequireKit which integrates with GuardKit.

Examples

Example 1: Add Logging

/task-refine TASK-042 "Add debug logging to authentication flow"

# System executes:
# 1. Load task from in_review/TASK-042.md
# 2. Load implementation plan and review context
# 3. Apply refinement: Add logger.debug() calls
# 4. Re-run tests (must pass)
# 5. Update task with refinement log
# 6. Keep task in in_review state

Example 2: Improve Variable Names

/task-refine TASK-043 "Rename variables for clarity: usr → current_user, pwd → password_hash"

# System executes:
# 1. Load task context
# 2. Refactor variable names across all files
# 3. Ensure tests still pass
# 4. Log refinement in task metadata

Example 3: Add Type Hints (Python)

/task-refine TASK-044 "Add type hints to public functions for better IDE support"

# System executes:
# 1. Analyze function signatures
# 2. Add type annotations (def login(user: User) -> AuthResult)
# 3. Run mypy type checker
# 4. Run tests (ensure type changes don't break)

Example 4: Extract Helper Function

/task-refine TASK-045 "Extract validation logic into _validate_input() helper"

# System executes:
# 1. Identify validation code blocks
# 2. Extract into private helper function
# 3. Update callers to use helper
# 4. Run tests (ensure behavior unchanged)

Multiple Related Tasks

When refinement affects multiple related tasks, review them together:

/task-status TASK-040 TASK-041 TASK-042 TASK-043

# Review related tasks before refining
# Ensure consistency across related implementations
/task-refine TASK-042 "Add logging to match TASK-040 pattern"

# Benefit: Consistent patterns across related tasks
# Use when: Refinement may affect related implementations

Note: For formal feature/epic hierarchies and requirements traceability, see RequireKit.

Multiple Refinement Cycles

Refinement Versioning

Each refinement cycle creates a versioned log entry:

# Task metadata after 3 refinements
refinements:
  - version: 1
    date: "2025-10-20T14:30:00Z"
    description: "Add debug logging to authentication flow"
    files_modified: ["src/auth/auth_service.py"]
    test_status: "passed"
    duration: "2 minutes"

  - version: 2
    date: "2025-10-20T15:45:00Z"
    description: "Rename usr → current_user for clarity"
    files_modified: ["src/auth/auth_service.py", "tests/test_auth.py"]
    test_status: "passed"
    duration: "3 minutes"

  - version: 3
    date: "2025-10-21T09:15:00Z"
    description: "Extract validation into _validate_credentials helper"
    files_modified: ["src/auth/auth_service.py"]
    test_status: "passed"
    duration: "4 minutes"

History Tracking

View Refinement History:

/task-status TASK-042 --refinements

# Output:
# TASK-042: Implement user authentication
# Status: in_review
# Refinements: 3 total
#
# 1. 2025-10-20 14:30 - Add debug logging
#    Files: src/auth/auth_service.py
#    Status: ✅ Passed tests
#
# 2. 2025-10-20 15:45 - Rename usr → current_user
#    Files: src/auth/auth_service.py, tests/test_auth.py
#    Status: ✅ Passed tests
#
# 3. 2025-10-21 09:15 - Extract validation helper
#    Files: src/auth/auth_service.py
#    Status: ✅ Passed tests

Git History Integration:

# Each refinement creates a commit
git log --oneline TASK-042

# Output:
# abc1234 [TASK-042] Refinement v3: Extract validation helper
# def5678 [TASK-042] Refinement v2: Rename usr → current_user
# ghi9012 [TASK-042] Refinement v1: Add debug logging
# jkl3456 [TASK-042] Initial implementation

When to Stop Refining

Stop Criteria:

✅ Good Stopping Points: - Code is readable and maintainable - All obvious improvements applied - No more "quick wins" visible - Team consensus on "good enough" - Time investment reaches diminishing returns

⚠️ Warning Signs (Approaching Over-Refinement): - 5+ refinement cycles on single task - Refinements take longer than original implementation - Tests start failing frequently - Changes become more than "minor adjustments" - Questioning original design decisions

❌ Stop Immediately If: - Considering architectural changes - Wanting to add new features - Original implementation seems flawed - Tests break and hard to fix - Scope expanding beyond original task

Alternative Actions: - Create new task for architectural improvements - Schedule team discussion for design review - Document technical debt item for later - Accept current state as "good enough for now"

Troubleshooting

Common Issues

Issue: Refinement Breaks Tests

Symptoms: - Tests passed before refinement - Tests failing after refinement - Error messages unclear

Diagnosis:

# Compare test output before/after
diff docs/state/{task_id}/test_results_original.json \
     docs/state/{task_id}/test_results_refinement_v1.json

# Review changes made
git diff HEAD~1 HEAD

# Run specific failing test
pytest tests/test_auth.py::test_login_valid_credentials -vv

Solutions: 1. Revert Refinement: git revert HEAD and try smaller change 2. Fix Tests: If test was too brittle, update test 3. Fix Implementation: Correct the refinement logic 4. Escalate to Re-work: Use /task-work if change too complex

Issue: Refinement Changes Behavior

Symptoms: - Tests pass but behavior different - Unexpected side effects - Integration tests failing

Diagnosis:

# Run full test suite (not just unit tests)
pytest tests/ -v --integration

# Check for side effects
git diff HEAD~1 HEAD --stat

# Review original acceptance criteria
cat tasks/in_review/TASK-042.md | grep -A 10 "Acceptance Criteria"

Solutions: 1. Revert if Unintended: Undo refinement, behavior must not change 2. Update Documentation: If behavior change intentional, document 3. Create New Task: If behavior change significant, track separately

Issue: Refinement Taking Too Long

Symptoms: - Refinement exceeds 10 minutes - Multiple attempts required - Complexity increasing

Diagnosis: - Is this really a "refinement" or a "re-work"? - Are you changing design, not just polish? - Should this be a new task?

Solutions: 1. Switch to /task-work: Abandon refinement, use full workflow 2. Break Down Change: Apply refinement in smaller steps 3. Accept Current State: Maybe "good enough" already achieved

Issue: Task Not in Eligible State

Error Message:

❌ Error: Cannot refine TASK-042

Task is in 'in_progress' state.
Required states: in_review, completed

Tasks in progress should use /task-work to complete implementation.

Solutions: 1. Complete task first: /task-work TASK-042 2. Wait for quality gates to pass 3. Once in in_review, retry refinement

Real-World Examples

Example 1: Adding Logging to Reviewed Task

Scenario: Task completed and in review. Code reviewer requests more logging.

Initial Task State: - State: in_review - Tests: 15/15 passing - Coverage: 87% - Review comment: "Add logging at key decision points"

Refinement Process:

# Step 1: Apply refinement
/task-refine TASK-042 "Add INFO logging at authentication decision points"

# System output:
Refinement v1: Adding logging to TASK-042
Analyzing code for decision points...
Adding logger.info() calls:
  - src/auth/auth_service.py:45 (login attempt)
  - src/auth/auth_service.py:67 (authentication success)
  - src/auth/auth_service.py:72 (authentication failure)

Re-running tests...
✅ All tests passing (15/15)
Coverage: 87% (unchanged)

Refinement complete: 2 minutes 15 seconds

Result: - Files modified: 1 (src/auth/auth_service.py) - Lines added: 3 (logger.info calls) - Tests: Still passing - Task remains in in_review (ready for re-review)

Example 2: Fixing Edge Case After Completion

Scenario: Task completed 2 weeks ago. Edge case discovered in production.

Initial Task State: - State: completed (archived) - Tests: 20/20 passing - Coverage: 92% - Issue: Empty string input causes crash (not covered by tests)

Refinement Process:

# Step 1: Move task back to in_review
/task-reopen TASK-043

# Step 2: Apply refinement
/task-refine TASK-043 "Add validation for empty string input"

# System output:
Refinement v1: Adding validation to TASK-043
Analyzing edge case...
Adding validation check:
  - src/utils/validator.py:23 (empty string check)

Generating test:
  - tests/test_validator.py:45 (test_validate_empty_string)

Re-running tests...
✅ All tests passing (21/21, +1 new test)
Coverage: 94% (+2%)

Refinement complete: 4 minutes 30 seconds

Result: - Files modified: 2 - Tests added: 1 - Coverage improved: 92% → 94% - Task back in in_review (ready for re-deployment)

Example 3: Multiple Refinement Cycle Scenario

Scenario: Iterative code review feedback over 3 cycles.

Cycle 1: Add Type Hints

/task-refine TASK-044 "Add type hints to all public methods"

# Result:
# - 15 functions annotated
# - mypy checks passing
# - Duration: 5 minutes

Cycle 2: Improve Docstrings

/task-refine TASK-044 "Add docstrings with parameter descriptions"

# Result:
# - 15 docstrings added (Google style)
# - Sphinx docs generated
# - Duration: 6 minutes

Cycle 3: Extract Magic Numbers

/task-refine TASK-044 "Extract magic numbers into named constants"

# Result:
# - 8 constants extracted (MAX_RETRIES, TIMEOUT_SECONDS, etc.)
# - Code more readable
# - Duration: 3 minutes

Total Refinement Investment: - 3 cycles - 14 minutes total - Original implementation: 45 minutes - Refinement overhead: 31% (acceptable)

When to Stop: - Code now highly readable - Type safe and well-documented - No more obvious improvements - Team consensus: "looks great!"

Related Workflows

• Agentecflow Lite Workflow - Complete workflow overview
• Quality Gates Workflow - Testing and quality enforcement
• Design-First Workflow - Design approval process
• Markdown Plans Workflow - Implementation plan format

FAQ

Q: Can I refine a task multiple times? A: Yes! Refinements are versioned and tracked. However, if you exceed 5 refinements, consider whether re-work is more appropriate.

Q: Does refinement trigger architectural review? A: No. Refinements are lightweight and skip Phase 2.5 (architectural review). Original review results are preserved.

Q: What if refinement breaks tests? A: System enters fix loop (1 attempt). If tests still fail, refinement is rejected and task state unchanged. Consider using /task-work for more complex changes.

Q: Can I refine tasks in blocked state? A: No. Tasks must be in in_review or completed state. Blocked tasks should use /task-work to unblock.

Q: Does refinement reset plan audit? A: No. Original plan audit preserved. Refinements tracked separately to show post-completion changes.

Q: Can refinement add new files? A: No. Refinements only modify existing files. New files require /task-work (full workflow).

Q: How do I undo a refinement? A: Use git revert to undo the refinement commit. Refinement history preserved in task metadata.

Q: Can I refine multiple tasks at once? A: No. Refinements are task-specific. Use individual /task-refine commands for each task.

Q: Does refinement count toward velocity? A: No. Refinements are maintenance, not new work. Original task completion counts toward velocity.

Q: When should I create a new task instead of refining? A: If the change: (1) adds new features, (2) requires new files, (3) changes architecture, or (4) takes >15 minutes. These should be new tasks.