Skip to content

Latest commit

 

History

History
715 lines (576 loc) · 18.5 KB

configuration.md

File metadata and controls

715 lines (576 loc) · 18.5 KB

Configuration Guide

reviewtask uses a flexible configuration system with progressive disclosure - start simple and add complexity only when needed.

🚀 Quick Start (NEW!)

For 90% of users, this is all you need:

{
  "language": "English",
  "ai_provider": "auto"
}

That's it! The tool automatically:

  • Detects your project type (Go, Node.js, Rust, Python, etc.)
  • Finds available AI providers (Cursor CLI or Claude Code)
  • Applies smart defaults for all settings
  • Shows which AI provider is being used at the start of every command

Configuration Levels

Level 1: Minimal (Recommended)

{
  "language": "English",
  "ai_provider": "auto"
}

Level 2: Basic Customization

{
  "language": "English",
  "ai_provider": "cursor",
  "model": "grok",
  "priorities": {
    "critical": "Security issues, data loss risks",
    "high": "Performance problems, crashes"
  }
}

Level 3: Advanced (Full Control)

{
  "priority_rules": {
    "critical": "Security vulnerabilities, authentication bypasses, data exposure risks",
    "high": "Performance bottlenecks, memory leaks, database optimization issues",
    "medium": "Functional bugs, logic improvements, error handling",
    "low": "Code style, naming conventions, comment improvements"
  },
  "task_settings": {
    "default_status": "todo",
    "auto_prioritize": true,
    "low_priority_patterns": ["nit:", "nits:", "minor:", "suggestion:", "consider:", "optional:", "style:"],
    "low_priority_status": "pending"
  },
  "ai_settings": {
    "user_language": "English",
    "validation_enabled": false,
    "verbose_mode": true
  },
  "done_workflow": {
    "enable_auto_resolve": "complete",
    "enable_verification": true,
    "enable_auto_commit": true,
    "enable_next_task_suggestion": true,
    "verifiers": {
      "build": "go build ./...",
      "test": "go test ./...",
      "lint": "golangci-lint run",
      "format": "gofmt -l ."
    }
  }
}

Done Workflow Configuration

The done_workflow section controls automation behavior for the reviewtask done command, providing a complete workflow from task completion to next task suggestion.

Configuration Patterns

Pattern 1: Minimal (Manual Workflow)

{
  "done_workflow": {
    "enable_auto_resolve": "disabled",
    "enable_verification": false,
    "enable_auto_commit": false,
    "enable_next_task_suggestion": false
  }
}

Use when: You want full manual control over commits and thread resolution.

Pattern 2: Recommended (Balanced Automation)

{
  "done_workflow": {
    "enable_auto_resolve": "complete",
    "enable_verification": true,
    "enable_auto_commit": true,
    "enable_next_task_suggestion": true
  }
}

Use when: You want automation with safety (verifies before committing, resolves only when all tasks done).

Pattern 3: Maximum Automation

{
  "done_workflow": {
    "enable_auto_resolve": "immediate",
    "enable_verification": true,
    "enable_auto_commit": true,
    "enable_next_task_suggestion": true
  }
}

Use when: You trust the automation and want immediate feedback loop.

Settings Explained

enable_auto_resolve - Thread resolution mode:

  • "immediate": Resolve thread right after task completion
  • "complete": Resolve only when all comment tasks are done (recommended)
  • "disabled": Manual resolution with reviewtask resolve

enable_verification - Run quality checks:

  • Executes build, test, lint, format commands before marking done
  • Prevents incomplete work from being marked complete
  • Auto-detected commands based on project type

enable_auto_commit - Automatic commit:

  • Creates structured commit with Co-authored-by tag
  • Skip with --skip-commit flag when needed
  • Commit message includes task context

enable_next_task_suggestion - Task recommendation:

  • Shows next recommended task after completion
  • Based on priority (critical > high > medium > low)
  • Skip with --skip-suggestion flag

Verification Commands

Customize verification commands per project type:

Go Project:

{
  "done_workflow": {
    "verifiers": {
      "build": "go build ./...",
      "test": "go test -short ./...",
      "lint": "golangci-lint run --fast",
      "format": "gofmt -l ."
    }
  }
}

Node.js Project:

{
  "done_workflow": {
    "verifiers": {
      "build": "npm run build",
      "test": "npm test",
      "lint": "npm run lint",
      "format": "npm run format:check"
    }
  }
}

Python Project:

{
  "done_workflow": {
    "verifiers": {
      "build": "python setup.py build",
      "test": "pytest tests/",
      "lint": "flake8 .",
      "format": "black --check ."
    }
  }
}

Configuration Management

Commands

# Interactive setup wizard
reviewtask init

# Validate your configuration
reviewtask config validate

# Migrate to simplified format (reduces ~46 lines to ~2-8 lines)
reviewtask config migrate

# Show current configuration
reviewtask config show

AI Provider Display

Every command now shows which AI provider is being used:

🤖 AI Provider: Cursor CLI (grok)

This helps you understand:

  • Which AI tool is active
  • What model is being used
  • If configuration is working correctly

Priority Rules

Customize how AI analyzes and prioritizes review comments:

Critical Priority

Comments matching this description get highest priority:

"critical": "Security vulnerabilities, authentication bypasses, data exposure risks"

Examples of critical issues:

  • SQL injection vulnerabilities
  • Authentication bypasses
  • Exposed API keys or secrets
  • Data privacy violations

High Priority

Important functionality and performance issues:

"high": "Performance bottlenecks, memory leaks, database optimization issues"

Examples of high priority issues:

  • Memory leaks
  • N+1 query problems
  • Blocking I/O operations
  • Resource exhaustion risks

Medium Priority

Standard functional improvements:

"medium": "Functional bugs, logic improvements, error handling"

Examples of medium priority issues:

  • Logic errors
  • Missing error handling
  • Edge case bugs
  • API inconsistencies

Low Priority

Style and minor improvements:

"low": "Code style, naming conventions, comment improvements"

Examples of low priority issues:

  • Code formatting
  • Variable naming
  • Comment quality
  • Documentation improvements

Task Settings

Default Status

Set the default status for new tasks:

"default_status": "todo"

Options: todo, doing, done, pending, cancel

Auto-Prioritization

Enable automatic priority assignment based on priority rules:

"auto_prioritize": true

Low-Priority Detection

Automatically detect and handle low-priority comments:

"low_priority_patterns": ["nit:", "nits:", "minor:", "suggestion:", "consider:", "optional:", "style:"],
"low_priority_status": "pending"

Pattern Matching:

  • Patterns are case-insensitive
  • Matches comments starting with patterns or containing them after newlines
  • Common patterns for code review tools (like CodeRabbit nits)

Example matches:

  • "nit: Consider using const instead of let"
  • "minor: This could be optimized"
  • "suggestion: Maybe extract this to a function"

AI Settings

User Language

Set the language for AI-generated content:

"user_language": "English"

Supported languages include English, Japanese, and others based on AI provider capabilities.

Model Configuration

Specify the AI model to use:

"model": "sonnet"

Supported models depend on your AI provider (Claude CLI, etc.)

Real-time Processing

Enable real-time task saving and streaming:

"realtime_saving_enabled": true,
"stream_processing_enabled": true
  • realtime_saving_enabled: Save tasks immediately as they're generated
  • stream_processing_enabled: Process comments in parallel with streaming results

Processing Modes

Standard Mode (Default)

"validation_enabled": false

Fast processing with individual comment analysis.

Validation Mode

"validation_enabled": true,
"max_retries": 5,
"quality_threshold": 0.8

Two-stage validation with retry logic and quality scoring.

Advanced AI Settings

{
  "ai_settings": {
    "verbose_mode": false,               // Enable detailed debug logging
    "validation_enabled": true,          // Enable AI task validation
    "max_retries": 5,                    // Validation retry attempts
    "quality_threshold": 0.8,            // Minimum validation score (0.0-1.0)
    "deduplication_enabled": true,       // AI-powered task deduplication
    "similarity_threshold": 0.8,         // Task similarity detection threshold
    "process_nitpick_comments": false,   // Process CodeRabbit nitpick comments
    "nitpick_priority": "low",           // Priority for nitpick-generated tasks
    "enable_json_recovery": true,        // Enable JSON recovery for incomplete responses
    "max_recovery_attempts": 3,          // Maximum JSON recovery attempts
    "partial_response_threshold": 0.7,   // Minimum threshold for partial responses
    "log_truncated_responses": true,     // Log truncated responses for debugging
    "enable_batch_processing": false     // v3.x only: Batch processing with existing task awareness (default in v4.0)
  }
}

Prompt Profiles (Default: v2)

Select the prompt style used for task generation:

{
  "ai_settings": {
    "prompt_profile": "v2"  // one of: v2 (alias: rich), compact, minimal, legacy
  }
}

Tips:

  • v2 is the default and recommended for most cases.
  • Use legacy only to compare with previous behavior or for fallback.

Prompt Templates

reviewtask uses customizable prompt templates for AI task generation. Templates are stored in the prompts/ directory.

Template Structure

Templates use Go template syntax with the following variables:

  • {{.LanguageInstruction}} - Language-specific instructions
  • {{.File}} - The file path of the comment
  • {{.Line}} - The line number of the comment
  • {{.Author}} - The comment author
  • {{.Comment}} - The comment body text

Customizing Templates

  1. Edit the template file in prompts/simple_task_generation.md
  2. No recompilation needed - changes take effect immediately
  3. Use markdown format for better readability

Example Template

# Task Extraction Assistant

{{.LanguageInstruction}}Generate tasks from the following comment.

## Comment Details
**File:** {{.File}}:{{.Line}}
**Author:** {{.Author}}
**Comment:** {{.Comment}}

## Response Format
Return a JSON array with tasks...
  • Render prompts locally without AI to inspect differences:
reviewtask debug fetch review 123
reviewtask debug prompt 123 --profile v2
reviewtask debug prompt 123 --profile legacy

JSON Recovery and Retry Features

Advanced recovery mechanisms for handling incomplete AI responses:

JSON Recovery

"enable_json_recovery": true,
"max_recovery_attempts": 3,
"partial_response_threshold": 0.7
  • Extracts valid tasks from truncated JSON responses
  • Cleans up malformed JSON syntax
  • Validates recovered data before processing

Intelligent Retry

"max_retries": 5

Smart retry strategies based on error patterns:

  • Automatic prompt size reduction for token limit errors
  • Exponential backoff for rate limiting
  • Pattern detection for common truncation issues

Response Monitoring

"log_truncated_responses": true

Tracks API performance and provides optimization insights:

  • Response size and truncation pattern analysis
  • Success rate tracking and error distribution
  • Performance analytics in .pr-review/response_analytics.json

Task Deduplication

AI-powered task deduplication prevents duplicate tasks:

"deduplication_enabled": true,
"similarity_threshold": 0.8
  • Compares task content using AI similarity analysis
  • Configurable similarity threshold (0.0-1.0)
  • Preserves existing task statuses during deduplication

AI Review Tool Integration

CodeRabbit Integration

Special handling for CodeRabbit code review comments:

"process_nitpick_comments": false,
"nitpick_priority": "low"
  • Control whether to process nitpick comments as tasks
  • Set priority level for nitpick-generated tasks
  • Integrates with low-priority detection patterns

Codex Integration (NEW)

Support for Codex (chatgpt-codex-connector) embedded review comments:

Automatic Detection:

  • Detects chatgpt-codex-connector username or reviews containing "codex"
  • Parses structured comments from review body
  • Extracts priority badges (P1/P2/P3) and GitHub permalinks
  • Converts to standard task format automatically

Priority Mapping:

P1 (🟠 orange) → HIGH priority
P2 (🟡 yellow) → MEDIUM priority
P3 (🟢 green)  → LOW priority

Example Codex Review Format:

https://github.com/owner/repo/blob/hash/file.py#L1-L5
**![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat) Fix critical issue**

Description of the issue that needs to be addressed...

Features:

  • No configuration required - works automatically
  • Duplicate review detection (Codex sometimes submits twice)
  • Compatible with all existing task management features
  • Thread auto-resolution not available (embedded comments have no thread ID)

GitHub Thread Auto-Resolution

Automatically resolve review threads when tasks are completed:

"auto_resolve_mode": "complete"

Available modes:

  • complete (default) - Resolve thread when ALL tasks from a comment are completed
    • done tasks: Always OK
    • cancel tasks: Must have posted cancel reason (CancelCommentPosted: true)
    • pending tasks: Block resolution
    • todo/doing tasks: Block resolution
  • immediate - Resolve thread immediately when each task is marked as done
  • disabled - Never auto-resolve (use reviewtask resolve for manual control)

Default: complete (smart resolution based on all tasks from same comment)

When enabled:

  • Comment-level tracking ensures all feedback is addressed before resolution
  • Provides visual confirmation that feedback has been addressed
  • Reduces manual cleanup work for PR authors
  • Works with standard GitHub comments (Codex embedded comments have no thread ID)

Requirements:

  • Valid GitHub authentication with repository write access
  • GraphQL API access (always available with standard GitHub tokens)
  • Tasks must have valid SourceCommentID (automatically populated)

Manual resolution: Use reviewtask resolve <task-id> or reviewtask resolve --all for manual thread resolution when auto-resolve is disabled or for specific control.

Environment Variables

Override configuration using environment variables:

# GitHub authentication
export GITHUB_TOKEN="your_github_token"

# AI provider settings
export REVIEWTASK_VERBOSE=true
export REVIEWTASK_VALIDATION=true

# GitHub Enterprise (if applicable)
export GITHUB_API_URL="https://github.company.com/api/v3"

Configuration Examples

Development Team Setup

For a development team focusing on security and performance:

{
  "priority_rules": {
    "critical": "Security vulnerabilities, authentication issues, data exposure, production failures",
    "high": "Performance problems, memory leaks, database issues, breaking changes",
    "medium": "Functional bugs, error handling, business logic issues",
    "low": "Code style, documentation, minor refactoring suggestions"
  },
  "task_settings": {
    "default_status": "todo",
    "auto_prioritize": true,
    "low_priority_patterns": ["nit:", "style:", "docs:", "typo:", "minor:"],
    "low_priority_status": "pending"
  },
  "ai_settings": {
    "validation_enabled": true,
    "quality_threshold": 0.9,
    "deduplication_enabled": true,
    "verbose_mode": false
  }
}

Open Source Project Setup

For open source projects with many contributors:

{
  "priority_rules": {
    "critical": "Security issues, breaking changes, license violations",
    "high": "API changes, performance regressions, compatibility issues",
    "medium": "Feature bugs, documentation errors, test failures",
    "low": "Code style, variable naming, comment improvements"
  },
  "task_settings": {
    "default_status": "todo",
    "low_priority_patterns": ["nit:", "suggestion:", "consider:", "optional:"],
    "low_priority_status": "pending"
  },
  "ai_settings": {
    "process_nitpick_comments": false,
    "deduplication_enabled": true,
    "similarity_threshold": 0.85
  }
}

Debug and Development Setup

For debugging and development work:

{
  "ai_settings": {
    "verbose_mode": true,
    "validation_enabled": true,
    "max_retries": 3,
    "enable_json_recovery": true,
    "log_truncated_responses": true,
    "deduplication_enabled": false
  }
}

Configuration Best Practices

Priority Rules

  • Use specific, actionable descriptions
  • Align with your team's development priorities
  • Include examples that match your codebase
  • Review and update regularly based on experience

Task Settings

  • Set realistic default statuses for your workflow
  • Customize low-priority patterns for your review style
  • Consider your team's task management preferences

AI Settings

  • Enable validation mode for critical projects
  • Use verbose mode during initial setup and troubleshooting
  • Adjust similarity thresholds based on your task deduplication needs
  • Enable JSON recovery for better reliability

Performance Tuning

  • Start with default settings
  • Enable verbose mode to understand processing behavior
  • Adjust retry and threshold settings based on your AI provider's characteristics
  • Monitor response analytics for optimization opportunities

Troubleshooting Configuration

Invalid Configuration

# Validate configuration syntax
reviewtask init  # Re-initializes with defaults if config is invalid

Priority Assignment Issues

# Enable verbose mode to see priority assignment logic
# Edit .pr-review/config.json:
{
  "ai_settings": {
    "verbose_mode": true
  }
}

Task Deduplication Problems

# Adjust similarity threshold or disable deduplication
{
  "ai_settings": {
    "deduplication_enabled": false,
    "similarity_threshold": 0.7  // Lower = less strict
  }
}

Processing Performance

# Enable validation and recovery for better reliability
{
  "ai_settings": {
    "validation_enabled": true,
    "enable_json_recovery": true,
    "max_retries": 5
  }
}

For more advanced configuration scenarios, see the Troubleshooting Guide or check the project's GitHub repository for examples.