--- name: coderabbit-triage description: Analyze code review findings and create execution plan. Decides parallel vs sequential fixing based on issue severity and independence. Returns structured task list with clear fixer instructions. --- # Triaging Issues ## Overview This skill transforms CodeRabbit's raw findings into an executable task plan. It analyzes issues by severity, checks for dependencies, and decides the optimal execution strategy (parallel fixers vs sequential). **Input**: JSON from `coderabbit-request` **Output**: Structured task dispatch plan with fixer instructions **When to use**: After CodeRabbit review completes, before dispatching fixer subagents. ## Decision Logic ### Step 1: Count and Categorize Analyze the issue distribution: ```text Critical (security, data corruption, crashes): - Race conditions, missing auth/validation, unsafe state mutations - Must fix immediately, cannot ship with these Important (bugs, performance issues, missing error handling): - Logic errors, performance regressions, unhandled edge cases - Should fix before merge, affects product quality Minor (style, simplification, documentation): - Code clarity, pattern consistency, comments - Can defer but should fix for consistency ``` ### Step 2: Identify Independent Domains For critical issues, check if they're in the same domain: **Independent** (can fix in parallel): - Race condition in webhook async handler (domain: concurrency) - Missing signature verification (domain: security) - Missing error logging (domain: observability) **Dependent** (must fix sequentially): - Missing signature verification depends on understanding webhook flow - Missing error handling in same flow that signature relies on - Both in same file and related code paths **Same domain** (likely sequential): - Race condition in webhook handler AND race condition in retry logic - Both race conditions, likely need same fix pattern ### Step 3: Check File/Region Overlap Before deciding strategy, check if issues share files or have overlapping line ranges: ```text File overlap check: - Group all issues by file path - If multiple issues target the same file → they are DEPENDENT - Same-file issues cannot run in parallel (risk of merge conflicts) Region overlap check (for same-file issues): - If line ranges overlap or are within 20 lines → tightly coupled - If line ranges are far apart but same file → still dependent (file lock) Example: Task 1: src/webhooks.ts:42 (signature verification) Task 2: src/webhooks.ts:89 (idempotency handling) Task 3: src/webhooks.ts:156 (error logging) → All target same file → DEPENDENT → use SINGLE_COMPREHENSIVE or BATCH_SEQUENTIAL ``` ### Step 4: Decide Execution Strategy ```text IF 0 critical issues: Strategy: "COMPLETE" Status: "No critical issues found" Offer: "Fix important + minor issues?" IF 1-3 critical AND all in DIFFERENT files AND non-overlapping: Strategy: "PARALLEL_CRITICAL" Pattern: Dispatch each critical as separate subagent Then: Sequential important/minor fixers Prerequisite: No two critical issues share the same file IF critical issues share same file OR have overlapping regions: Strategy: "SINGLE_COMPREHENSIVE" Pattern: One fixer with full file context handles all issues in that file Reason: Prevents merge conflicts, simpler coordination for same-file edits IF 3+ critical OR critical issues have logical dependencies: Strategy: "SEQUENTIAL" Pattern: Fix each critical, verify, then move to next Reason: Complex dependencies require verification between fixes IF only important/minor (no critical): Strategy: "BATCH_SEQUENTIAL" Pattern: Group by file, fix each file completely before moving to next Reason: Reduces context switching, prevents same-file conflicts ``` ### Step 5: Create Task Dispatch Plan For each issue, create a fixer task: ```json { "total_issues": 3, "by_severity": { "critical": 1, "important": 2, "minor": 0 }, "strategy": "SINGLE_COMPREHENSIVE", "analysis": { "all_issues_same_file": true, "file": "src/webhooks.ts", "reason": "All 3 issues target same file - must fix sequentially to prevent conflicts", "critical_are_independent": false, "important_are_related": true, "minor_count": 0 }, "tasks": [ { "task_id": 1, "severity": "critical", "priority": 1, "domain": "payment-webhook-security", "file": "src/webhooks.ts", "line": 42, "issue": "Missing HMAC signature verification for webhook authenticity", "coderabbit_suggestion": "Add HMAC-SHA256 signature verification using crypto module. Compare against timestamp to prevent replay attacks.", "fixer_instructions": [ "1. Import crypto.timingSafeEqual at top of file", "2. At webhook handler entry (line 42), before processing body:", " - Extract 'X-Webhook-Signature' header", " - Extract request body as raw string", " - Compute HMAC-SHA256 signature using process.env.WEBHOOK_SECRET", " - Use timingSafeEqual to compare (prevents timing attacks)", " - Return 401 Unauthorized if verification fails", "3. Extract 'X-Webhook-Timestamp' header", "4. Verify timestamp is within 5 minutes of current time", "5. Return 401 if timestamp too old (replay attack protection)", "6. Add structured logging: {timestamp, signature_valid, webhook_id, processed: true}", "7. Run: npm test -- src/webhooks.test.ts", "8. Verify all webhook security tests pass" ], "constraints": [ "DO NOT modify webhook body parsing logic", "DO NOT change authentication for other endpoints", "DO NOT remove existing error handling", "ONLY modify webhook entry point validation" ], "estimated_time": "10 minutes", "can_run_parallel_with": [], "must_complete_before": [2, 3], "same_file_as": [2, 3] }, { "task_id": 2, "severity": "important", "priority": 2, "domain": "webhook-concurrency", "file": "src/webhooks.ts", "line": 89, "issue": "Race condition: multiple concurrent webhook calls can update state simultaneously", "coderabbit_suggestion": "Implement idempotency key handling. Store processed keys in cache with TTL to deduplicate retries.", "fixer_instructions": [ "1. Create idempotency key map at module level:", " const idempotencyCache = new Map()", "2. At webhook handler (line 89), extract 'X-Idempotency-Key' header", "3. Check if key exists in cache:", " - IF exists: return cached result (prevents duplicate processing)", " - IF not exists: continue processing", "4. Process webhook (database writes, event emits, etc)", "5. Store result in cache with 24-hour TTL:", " idempotencyCache.set(key, {result, timestamp: Date.now()})", "6. Clean up old entries (cron every hour):", " - Remove keys older than 24 hours", "7. Add test: duplicate webhook with same key returns same result", "8. Add test: webhook with different key processes independently", "9. Run: npm test -- src/webhooks.test.ts", "10. Verify idempotency and concurrency tests pass" ], "constraints": [ "DO NOT modify signature verification logic (task 1)", "DO NOT remove existing error handling", "DO NOT change database schema", "ONLY add idempotency deduplication" ], "estimated_time": "12 minutes", "can_run_parallel_with": [], "depends_on": [1], "must_complete_before": [3], "same_file_as": [1, 3] }, { "task_id": 3, "severity": "important", "priority": 3, "domain": "webhook-observability", "file": "src/webhooks.ts", "line": 156, "issue": "Missing error logging for webhook failures. Makes debugging production issues difficult.", "coderabbit_suggestion": "Add structured logging with timestamp, error type, and webhook ID. Include full error stack.", "fixer_instructions": [ "1. Import logger at top (ensure it's structured JSON logger)", "2. At webhook handler (line 156), add pre-processing log:", " logger.info({event: 'webhook_received', webhook_id, timestamp, domain})", "3. Wrap webhook processing in try-catch:", " - On success: logger.info({event: 'webhook_processed', webhook_id, duration_ms})", " - On error: logger.error({event: 'webhook_failed', webhook_id, error_type, error_message, stack})", "4. For specific error types, add context:", " - If signature fails: log 'signature_verification_failed'", " - If database fails: log 'database_operation_failed', include operation type", " - If event emit fails: log 'event_emission_failed'", "5. Add log levels:", " - Validation failures: warn", " - Processing failures: error", " - Success: info", "6. Verify all logs have: webhook_id, timestamp, event_type, error details", "7. Run: npm test -- src/webhooks.test.ts", "8. Verify logging tests pass" ], "constraints": [ "DO NOT change webhook processing logic", "DO NOT log sensitive data (secrets, full bodies)", "DO NOT break existing tests", "ONLY add observability logging" ], "estimated_time": "8 minutes", "can_run_parallel_with": [], "depends_on": [1, 2], "same_file_as": [1, 2] } ], "execution_plan": { "phase_1_sequential": [ "Step 1: Fix task 1 (signature verification) - critical, must complete first", "Step 2: Fix task 2 (idempotency handling) - depends on task 1 completing", "Step 3: Fix task 3 (error logging) - depends on tasks 1 and 2 completing" ], "reason": "All tasks target src/webhooks.ts - sequential execution prevents merge conflicts", "verification": { "after_each_fix": "Run npm test -- src/webhooks.test.ts", "after_all_fixes": [ "Run full test suite: npm test", "Re-run coderabbit: coderabbit --prompt-only --type uncommitted", "Verify zero issues remain" ] } }, "summary": "3 issues identified in src/webhooks.ts. Strategy: SINGLE_COMPREHENSIVE (all same file). Sequential execution required to prevent conflicts. Estimated total time: 30 minutes." } ``` ## Verification Checklist Before returning plan, verify: - [ ] Every issue has a task_id - [ ] Severity is accurately assessed - [ ] Dependencies identified correctly - [ ] Strategy choice justified by analysis - [ ] Fixer instructions are clear and specific - [ ] Constraints explicitly listed - [ ] Estimated times are realistic - [ ] Parallel groups don't have conflicts - [ ] All CodeRabbit suggestions referenced ## Key Principles **Analysis over assumption**: Check real dependencies, don't assume everything is parallel. **Clarity for fixers**: Fixer subagents need exact step-by-step instructions, not vague guidance. **Constraint enforcement**: Tell fixers explicitly what NOT to change, prevents scope creep. **Transparency**: Explain WHY you chose a strategy, not just what it is. ## Common Patterns **All independent critical issues (different files)**: ```json { "strategy": "PARALLEL_CRITICAL", "analysis": { "files_are_independent": true, "no_file_overlap": true }, "tasks": [ {"task_id": 1, "file": "src/auth.ts", "can_run_parallel_with": [2, 3]}, {"task_id": 2, "file": "src/payments.ts", "can_run_parallel_with": [1, 3]}, {"task_id": 3, "file": "src/notifications.ts", "can_run_parallel_with": [1, 2]} ] } ``` **Mix of critical and important**: ```json { "strategy": "SEQUENTIAL_WITH_PARALLEL_IMPORTANT", "phase_1": ["critical issues"], "phase_2": ["important issues in parallel"] } ``` **Complex interdependencies**: ```json { "strategy": "SEQUENTIAL", "must_complete_before": { "task_2": ["task_1"], "task_3": ["task_1", "task_2"] } } ``` ## Integration Points ```text coderabbit-request ↓ (outputs JSON) coderabbit-triage ↓ (outputs task plan) coderabbit-fix (dispatched per task) ``` Return structured task plan. Main agent will dispatch fixer subagents based on strategy and parallelization groups.