Workflow Guide¶

Learn how to integrate reviewtask into your daily development workflow for maximum productivity and systematic PR review management.

Core Workflow Philosophy¶

reviewtask is designed around three core principles:

Zero Feedback Loss: Every actionable review comment becomes a tracked task
State Preservation: Your work progress is never lost during tool operations
AI-Assisted, Human-Controlled: AI provides intelligent analysis while you maintain full control

Daily Development Routine¶

Morning Startup¶

Start your day by understanding what needs attention:

reviewtask show           # What should I work on today?
reviewtask status         # Overall progress across all PRs

What you'll see: - Current or next recommended task with full context - Progress overview across all your active PRs - Priority distribution and completion status

During Implementation¶

As you work on tasks, maintain visibility and track progress:

# Get full context for a specific task
reviewtask show <task-id>

# Start working on the task (v3.0.0)
reviewtask start <task-id>

# Complete the work...

# Mark task as completed with full automation (v3.0.0 - RECOMMENDED)
reviewtask done <task-id>
# What happens automatically:
# 1. Verification (build/test/lint checks)
# 2. Status update to "done"
# 3. Auto-commit with structured message
# 4. Review thread resolution (when all comment tasks complete)
# 5. Next task suggestion

Skip Options - Skip individual automation phases when needed:

Skip verification (build, test, lint checks):

reviewtask done <task-id> --skip-verification

Task will be marked as done without running verification checks.

Skip automatic commit:

reviewtask done <task-id> --skip-commit

Task will be marked as done without creating a git commit.

Skip thread resolution:

reviewtask done <task-id> --skip-resolve

Task will be marked as done without resolving the GitHub review thread.

Skip next task suggestion:

reviewtask done <task-id> --skip-suggestion

Task will be marked as done without suggesting the next task.

Done Command Automation:

The reviewtask done command provides complete workflow automation:

Verification Phase - Runs build, test, lint, and format checks
Configured via done_workflow.verifiers in config
Auto-detected based on project type (Go, Node.js, Python, Rust)
Fails if checks don't pass (prevents incomplete work)
Status Update - Marks task as "done" in local storage
Auto-Commit - Creates structured commit with:
Task description and context
Reference to review comment
Co-authored-by tag for attribution
Thread Resolution - Resolves GitHub review thread based on mode:
immediate: Resolve right after task completion
complete: Resolve only when all comment tasks done (recommended)
disabled: Manual resolution
Next Task Suggestion - Shows next recommended task by priority

Note: Traditional commands (reviewtask update <task-id> doing/done) are still supported, but start and done provide better workflow integration.

When Blocked¶

Handle blocked or low-priority work systematically:

# Put task on hold (v3.0.0)
reviewtask hold <task-id>

# Find next available task
reviewtask show

# Check overall progress
reviewtask status

Note: The traditional reviewtask update <task-id> pending command is still supported, but the new hold command is more intuitive.

Handling Updated Reviews¶

When reviewers add new comments or feedback:

# Re-run analysis to get new feedback
reviewtask

# Tool automatically:
# - Preserves existing task statuses
# - Adds new tasks for new comments
# - Cancels outdated tasks if comments change significantly

PR Review Response Workflow¶

The Golden Path¶

This is the recommended workflow for handling PR reviews:

1. Receive Review Notification¶

PR receives reviews with comments and feedback
Developer needs to address feedback systematically

2. Generate Actionable Tasks¶

# Convert all review feedback into tracked tasks
reviewtask

3. Review What Needs to be Done¶

# See current work or next recommended task
reviewtask show

4. Work on Tasks Systematically¶

# Start working on a task (v3.0.0)
reviewtask start <task-id>

# Complete implementation (v3.0.0)
reviewtask done <task-id>

5. Handle Updated Reviews¶

# Re-run when reviewers add new comments
reviewtask
# Tool automatically preserves your work progress

Task Lifecycle Management¶

Task Statuses¶

Understanding and using task statuses effectively:

todo - Ready to work on (default for new tasks)
doing - Currently in progress (use for active work)
done - Completed (work finished)
pending - Blocked or low priority (use for blockers or nits)
cancel - No longer relevant (auto-assigned when comments change)

Status Transitions¶

Typical task status flow:

todo → doing → done     (normal completion)
todo → pending          (blocked or low priority)
pending → doing → done  (unblocked and completed)
any → cancel           (comment becomes outdated)

Best Practices¶

Use doing status: Mark tasks as in progress to track active work
Don't skip statuses: Move tasks through appropriate states
Mark blockers as pending: Use pending for blocked or low-priority work
Let tool handle cancel: Don't manually cancel tasks; let the tool detect changes

Team Collaboration Rules¶

For PR Authors¶

When you receive reviews: 1. Run reviewtask immediately after receiving reviews 2. Update task statuses as you complete work
3. Never manually edit .pr-review/ files 4. Use task completion as readiness indicator

Daily practice:

# Morning: Check what needs attention
reviewtask status

# During work: Track progress (v3.0.0)
reviewtask start <task-id>
# ... work ...
reviewtask done <task-id>

# When stuck: Put on hold and find next task (v3.0.0)
reviewtask hold <task-id>
reviewtask show

For Reviewers¶

Writing effective reviews: 1. Write actionable, specific feedback 2. Use clear priority indicators (security issues, nits, etc.) 3. Trust that feedback will be systematically addressed 4. Follow up reviews add incremental tasks automatically

Review workflow: - Initial review creates comprehensive task list - Follow-up reviews add only new/changed feedback - Completed tasks remain completed across review iterations

For Teams¶

Integration points: 1. Integrate task status into standup discussions 2. Use task completion as PR readiness indicator 3. Treat persistent pending tasks as team blockers 4. Share configuration patterns across team repositories

Advanced Workflow Patterns¶

Multi-PR Management¶

Working across multiple PRs simultaneously:

# Check all PRs
reviewtask status --all

# Work on specific PR (v3.0.0: simplified syntax)
cd /path/to/pr-branch
reviewtask show

# Check specific PR status (v3.0.0: positional argument)
reviewtask status 123
reviewtask status 456

Priority-Based Workflow¶

Focus on high-impact work first:

# Review task priorities
reviewtask stats

# Configure priority rules in .pr-review/config.json
# Work on critical/high priority tasks first
# Leave low-priority tasks for later or mark as pending

Batch Processing¶

Handle multiple tasks efficiently:

# Get overview of all tasks
reviewtask status

# Process similar tasks together
# Use task descriptions to group related work
# Update multiple task statuses as you complete batches

Debugging and Troubleshooting Workflow¶

When Things Go Wrong¶

Missing tasks:

# Force refresh to reprocess all comments
reviewtask --refresh-cache

Authentication issues:

# Check authentication status
reviewtask auth status
reviewtask auth check

# Re-authenticate if needed
reviewtask auth logout
reviewtask auth login

Task generation problems:

# Test specific phases independently
reviewtask debug fetch review 123    # Fetch reviews only
reviewtask debug fetch task 123      # Generate tasks only

# Render analysis prompt locally (no AI) for inspection/A/B comparison
reviewtask debug prompt 123 --profile v2
reviewtask debug prompt 123 --profile legacy

# Enable verbose mode in .pr-review/config.json
{
  "ai_settings": {
    "verbose_mode": true
  }
}

Performance Issues¶

Large PRs: - Tool automatically optimizes for large PRs - Uses parallel processing and automatic chunking - Enable verbose mode to see optimization details

API rate limits:

# Check rate limit status
reviewtask auth check

# Use cache to reduce API calls
# Avoid --refresh-cache unless necessary

Integration with Development Tools¶

Git Integration¶

reviewtask works seamlessly with Git workflows:

# Standard Git workflow
git checkout feature-branch
# ... receive PR reviews ...
reviewtask                    # Generate tasks
reviewtask show              # Work on tasks
# ... make changes ...
git add .
git commit -m "Address PR feedback"
git push

IDE Integration¶

Task context in your editor: - Use reviewtask show <task-id> to get full task context - Copy task descriptions into commit messages - Reference task IDs in commit messages for traceability

CI/CD Integration¶

Automated checks:

# In CI pipeline, check for pending tasks
reviewtask status --pr $PR_NUMBER
# Fail build if critical tasks remain incomplete

Configuration for Different Workflows¶

Individual Developer¶

{
  "task_settings": {
    "default_status": "todo",
    "low_priority_status": "pending"
  },
  "ai_settings": {
    "verbose_mode": false,
    "validation_enabled": false
  }
}

Team Development¶

{
  "priority_rules": {
    "critical": "Security, breaking changes, production issues",
    "high": "Performance, functionality, API changes",
    "medium": "Bugs, improvements, error handling",
    "low": "Style, documentation, minor suggestions"
  },
  "task_settings": {
    "auto_prioritize": true,
    "low_priority_patterns": ["nit:", "style:", "suggestion:"]
  }
}

High-Quality Projects¶

{
  "ai_settings": {
    "validation_enabled": true,
    "quality_threshold": 0.9,
    "deduplication_enabled": true,
    "max_retries": 5
  }
}

Measuring Success¶

Key Metrics¶

Track these indicators of successful reviewtask adoption:

Task Completion Rate: Percentage of tasks marked as done
Review Cycle Time: Time from review to PR approval
Feedback Loss: Number of review comments not addressed
Developer Satisfaction: Subjective measure of workflow improvement

Monitoring Commands¶

# Overall progress
reviewtask status --all

# Detailed analytics
reviewtask stats --all

# Individual PR analysis
reviewtask stats --pr 123

Getting Help¶

Self-Service Debugging¶

Enable verbose mode: Add detailed logging to understand tool behavior
Use debug commands: Test specific functionality independently
Check configuration: Verify settings match your workflow needs
Review documentation: Check command reference and troubleshooting guides

Community Support¶

GitHub Issues: Report bugs and request features
Documentation: Comprehensive guides and examples
Examples: Real-world configuration patterns and workflows

For detailed troubleshooting steps, see the Troubleshooting Guide.

For specific command usage, see the Command Reference.