--- name: debate-workflow version: 1.0.0 description: Structured multi-perspective debate for important architectural decisions and complex trade-offs auto_activates: - "architectural decision" - "design trade-off" - "framework selection" - "major refactoring" - "controversial change" - "multiple valid approaches" explicit_triggers: - /amplihack:debate confirmation_required: true token_budget: 3500 --- # Debate Workflow Skill ## Purpose Implement structured multi-perspective debate for important architectural decisions, design trade-offs, and complex problems where multiple valid approaches exist. ## When to Use This Skill **USE FOR:** - Major architectural decisions (framework selection, system design) - Complex trade-offs with no clear winner - Controversial changes affecting multiple teams - High-impact decisions requiring buy-in - When perspectives genuinely conflict **AVOID FOR:** - Simple implementation choices - Decisions with obvious correct answer - Time-sensitive hot fixes - Minor refactoring - Routine feature additions ## Configuration ### Core Parameters **Number of Perspectives:** - `3` - Default (security, performance, simplicity) - `5` - Extended (add: maintainability, user-experience) - `7` - Comprehensive (add: scalability, cost) **Debate Rounds:** - `2` - Quick (position + challenge) - `3` - Standard (position + challenge + synthesis) - `4-5` - Deep (multiple challenge/response cycles) **Convergence Criteria:** - `100%` - Strong consensus (all perspectives agree) - `2/3` - Majority rule (two-thirds agreement) - `synthesis` - Facilitator synthesizes best hybrid - `evidence` - Follow strongest evidence/arguments ## Standard Perspective Profiles **Security Perspective:** - Focus: Vulnerabilities, attack vectors, data protection - Questions: "What could go wrong? How do we prevent breaches?" - Agent: security agent **Performance Perspective:** - Focus: Speed, scalability, resource efficiency - Questions: "Will this scale? What are the bottlenecks?" - Agent: optimizer agent **Simplicity Perspective:** - Focus: Minimal complexity, ruthless simplification - Questions: "Is this the simplest solution? Can we remove abstractions?" - Agent: cleanup agent + reviewer agent **Maintainability Perspective:** - Focus: Long-term evolution, technical debt - Questions: "Can future developers understand this? How hard to change?" - Agent: reviewer agent + architect agent **User Experience Perspective:** - Focus: API design, usability, developer experience - Questions: "Is this intuitive? How will users interact with this?" - Agent: api-designer agent **Scalability Perspective:** - Focus: Growth capacity, distributed systems - Questions: "What happens at 10x load? 100x?" - Agent: optimizer agent + architect agent **Cost Perspective:** - Focus: Resource usage, infrastructure costs, development time - Questions: "What's the ROI? Are we over-engineering?" - Agent: analyzer agent ## Execution Process ### Step 1: Frame the Decision - **Use ambiguity agent** to clarify the decision to be made - **Use prompt-writer agent** to create clear decision prompt - Define decision scope and constraints - Identify stakeholder concerns - List evaluation criteria - Document explicit user requirements that constrain options - **CRITICAL: Frame decision as question, not predetermined answer** **Decision Framing Template:** ```markdown # Decision: [Brief Title] ## Question [One-sentence question to be debated] ## Context [Why this decision matters, background information] ## Constraints [Non-negotiable requirements, technical limitations] ## Evaluation Criteria [How we'll judge proposed solutions] ## Perspectives to Include [Which viewpoints are most relevant] ``` **Example:** ```markdown # Decision: Data Storage Strategy for User Analytics ## Question Should we use PostgreSQL with JSONB, MongoDB, or ClickHouse for storing and querying user analytics events? ## Context - 10M events/day expected at launch - 100M events/day within 2 years - Complex queries for dashboard analytics - Real-time and historical reporting needed ## Constraints - Must handle 10M events/day minimum - Query latency < 200ms for dashboards - Budget: $5K/month infrastructure - Team familiar with PostgreSQL, not ClickHouse ## Evaluation Criteria 1. Performance at scale 2. Query flexibility 3. Operational complexity 4. Cost at scale 5. Team learning curve ## Perspectives to Include Performance, Cost, Maintainability, Scalability ``` ### Step 2: Initialize Perspectives - Select N perspectives relevant to decision - **Spawn Claude subprocess for each perspective** - Each subprocess receives decision framing doc - Each subprocess assigned perspective profile - **No context sharing between perspectives yet** - Each forms initial position independently **Initial Position Requirements:** - State recommended approach - Provide 3-5 supporting arguments - Identify risks of alternative approaches - Quantify claims where possible ### Step 3: Debate Round 1 - Initial Positions - Collect initial positions from all perspectives - **Use analyzer agent** to synthesize positions - Document each perspective's recommendation - Identify areas of agreement - Identify areas of conflict - Surface assumptions made by each perspective **Round 1 Output Structure:** ```markdown ## Security Perspective: [Recommendation] Arguments For: 1. [Argument with evidence] 2. [Argument with evidence] 3. [Argument with evidence] Concerns About Alternatives: - [Alternative A]: [Specific concern] - [Alternative B]: [Specific concern] Assumptions: - [Assumption 1] - [Assumption 2] ``` ### Step 4: Debate Round 2 - Challenge and Respond - Share all Round 1 positions with all perspectives - Each perspective challenges other perspectives' arguments - Each perspective defends their position against challenges - **Use analyzer agent** to track argument strength - Identify which arguments withstand scrutiny - Document concessions and refinements **Challenge Format:** ```markdown ## [Perspective A] challenges [Perspective B] Challenge: [Question or counter-argument] Evidence: [Supporting data or examples] Request: [What would change your position?] ``` **Response Format:** ```markdown ## [Perspective B] responds to [Perspective A] Response: [Address the challenge] Concession: [Points where you agree or adjust] Counter: [Additional evidence or reasoning] ``` ### Step 5: Debate Round 3 - Find Common Ground - Identify points of consensus across perspectives - Surface remaining disagreements explicitly - Explore hybrid approaches combining insights - **Use architect agent** to design synthesis options - Validate hybrid approaches against all perspectives - Document convergence or divergence **Convergence Analysis:** ```markdown ## Areas of Agreement 1. [Consensus point 1] 2. [Consensus point 2] ## Remaining Disagreements 1. [Disagreement 1] - Security says: [position] - Performance says: [position] - Potential resolution: [hybrid approach] ## Hybrid Approaches Identified 1. [Hybrid Option 1] - Combines: [which perspectives] - Trade-offs: [explicit costs/benefits] ``` ### Step 6: Facilitator Synthesis - **Use architect agent** as neutral facilitator - **Use analyzer agent** to evaluate all arguments - Review all debate rounds systematically - Identify strongest evidence-based arguments - Make recommendation with confidence level - Document decision rationale thoroughly - Include dissenting views explicitly **Synthesis Structure:** ```markdown ## Facilitator Synthesis ### Recommendation [Clear statement of recommended approach] ### Confidence Level [High/Medium/Low] confidence based on: - Consensus level: [X% of perspectives agree] - Evidence quality: [Strong/Moderate/Weak] - Risk level: [Low/Medium/High if wrong] ### Rationale [Explanation of why this recommendation] ### Key Arguments That Won 1. [Argument that swayed decision] 2. [Argument that swayed decision] 3. [Argument that swayed decision] ### Key Arguments Against (Dissenting Views) 1. [Strongest counter-argument] 2. [Remaining concern] ### Implementation Guidance [How to execute this decision] ### Success Metrics [How we'll know if this was the right choice] ### Revisit Triggers [Conditions that would require reconsidering this decision] ``` ### Step 7: Decision Documentation - Create decision record: `decisions/YYYY-MM-DD-decision-name.md` - Document full debate transcript - Include all perspective arguments - Record synthesis and final decision - Store in memory using `store_discovery()` from `amplihack.memory.discoveries` - Update relevant architecture docs **Decision Record Template:** ```markdown # Decision Record: [Title] Date: [YYYY-MM-DD] Status: Accepted Decision Makers: [List perspectives included] ## Context [What decision was needed and why] ## Decision [What was decided] ## Consequences [What happens because of this decision] ## Alternatives Considered [What other options were debated] ## Debate Summary [Key arguments from each perspective] ## Dissenting Opinions [Perspectives that disagreed and why] ## Review Date [When to revisit this decision] --- ## Full Debate Transcript ### Round 1: Initial Positions [Complete positions from all perspectives] ### Round 2: Challenges and Responses [All challenge/response exchanges] ### Round 3: Convergence Analysis [Common ground and hybrid approaches] ### Facilitator Synthesis [Complete synthesis document] ``` ### Step 8: Implement Decision - **Use builder agent** to implement chosen approach - Follow the decided path from synthesis - Implement monitoring for success metrics - Set up alerts for revisit triggers - Document decision in code comments - Create runbook if operational complexity added ## Trade-Offs **Cost:** Multiple agent cycles, longer decision time **Benefit:** Well-reasoned decisions, surface hidden risks **Best For:** Decisions that are expensive to reverse ## Examples ### Example 1: API Design - REST vs GraphQL **Configuration:** - Perspectives: 5 (Simplicity, Performance, User-Experience, Maintainability, Cost) - Rounds: 3 - Convergence: Synthesis **Debate Summary:** - Simplicity: REST is straightforward, well-understood - Performance: GraphQL reduces over-fetching, fewer round trips - UX: GraphQL gives frontend flexibility, better DX - Maintainability: REST easier to version and evolve - Cost: GraphQL higher learning curve, more complex infrastructure **Result:** REST for initial MVP, GraphQL for v2 - Rationale: Team knows REST, faster to ship - Migration path: Add GraphQL layer in 6 months - Trigger: When frontend requests 3+ endpoints per view ### Example 2: Testing Strategy - Unit vs Integration Heavy **Configuration:** - Perspectives: 3 (Simplicity, Maintainability, Performance) - Rounds: 2 - Convergence: 2/3 majority **Debate Summary:** - Simplicity: Unit tests, mock all dependencies - Maintainability: Integration tests, test real interactions - Performance: Mix, optimize for feedback speed **Result:** 70% unit, 30% integration (Majority agreed) - Rationale: Unit tests faster feedback, integration tests catch real issues - Dissent: Simplicity wanted 90% unit tests (overruled by maintainability concerns) ### Example 3: Deployment Strategy - Kubernetes vs Serverless **Configuration:** - Perspectives: 5 (Cost, Simplicity, Scalability, Performance, Maintainability) - Rounds: 4 - Convergence: Synthesis (no majority) **Debate Summary:** - Long, contentious debate with no clear winner - Cost and Simplicity favored serverless - Scalability and Performance favored Kubernetes - Maintainability split (serverless simpler, k8s more control) **Result:** Serverless with k8s option researched - Rationale: Start simple, team small, serverless faster - Hybrid: Evaluate k8s at 10x scale or complex networking needs - Strong dissent documented: Performance perspective believes this will need revisiting soon ## Philosophy Alignment This workflow enforces: - **Perspective Diversity:** Multiple viewpoints surface hidden trade-offs - **Evidence-Based:** Arguments must be supported, not just opinions - **Transparent Trade-offs:** Dissent is documented, not hidden - **Structured Exploration:** Debate format prevents premature convergence - **Decision Quality:** Better decisions through rigorous analysis - **Learning:** Debate transcripts become organizational knowledge ## Integration with Default Workflow This workflow replaces Step 4 (Research and Design) of the DEFAULT_WORKFLOW when complex decisions require multi-perspective analysis. Implementation (Step 5) proceeds with the consensus decision.