Fix premature plan consolidation with explicit completion signal (TAS-79)

[yanismydj]

Summary

This PR fixes premature consolidation issues in multi-question plan mode by implementing an explicit completion signal mechanism. Previously, the bot would consolidate clarifying questions too early due to webhook debounce triggering after individual checkbox changes.

Changes

1. Explicit Completion Signal

• Users can now signal completion by commenting /done, done answering, finished answering, etc.
• Consolidation only triggers after receiving this explicit signal, not after individual checkbox state changes
• Completion signal comments are automatically deleted to keep tickets clean

2. Configurable Dynamic Debounce

• Replaced fixed 5-second timeout with formula-based calculation: baseMs + (questionCount * perQuestionMs), capped at maxMs
• Default configuration: 3s base + 1s per question, max 30s
• Configurable via environment variables:
  • WEBHOOK_CHECKBOX_DEBOUNCE_BASE_MS (default: 3000)
  • WEBHOOK_CHECKBOX_DEBOUNCE_PER_QUESTION_MS (default: 1000)
  • WEBHOOK_CHECKBOX_DEBOUNCE_MAX_MS (default: 30000)

3. Graceful Handling of Unanswered Questions

• Consolidation now tracks which questions were answered vs. skipped
• Provides clear feedback to users about question response statistics
• Unanswered questions treated as intentionally skipped and don't block progress

4. Improved Plan Mode UX

• Questions posted with clear instructions to use /done when finished
• Consolidated feedback includes answer statistics (e.g., "Answered: 3/5, Skipped: 2")
• Clear messaging that unanswered questions are treated as skipped

Technical Implementation

Modified Files:

• src/config.ts: Added webhook checkbox debounce configuration with dynamic calculation
• src/webhook/handler.ts:
  • Added completion signal detection (isCompletionSignal())
  • Implemented dynamic debounce calculation (calculateDebounceTimeout())
  • Modified handleCommentCreate() to detect and process completion signals
  • Updated handleCommentUpdate() to use dynamic debounce and respect completion signals
• src/queue/processor.ts:
  • Updated handlePlan() to instruct users about /done signal
  • Enhanced handleConsolidatePlan() to analyze and report question response statistics
• .env.example: Documented new configuration options

Testing Scenarios

The implementation handles:

• ✅ Single question scenarios (3s debounce)
• ✅ Multiple questions (3s + 1s per question, e.g., 8s for 5 questions)
• ✅ Completion signal variations (/done, done answering, etc.)
• ✅ Unanswered questions (treated as skipped, no blocking)
• ✅ Regular clarification flow (non-plan mode uses base timeout)

Related Linear Ticket

https://linear.app/opendoor/issue/TAS-79

🤖 Generated with Claude Code