@startuml discussion-stages
!theme plain
title Feature Discussion Stage Progression with Status Transitions

state "Feature Stage" as feature {
  [*] --> OPEN_F : feature.discussion.md created

  OPEN_F : status: OPEN
  OPEN_F : Participants discuss scope,\nplatform, requirements

  OPEN_F --> READY_FOR_DESIGN : ≥2 READY votes\n(human only if\nallow_agent_votes: false)

  READY_FOR_DESIGN : status: READY_FOR_DESIGN
  READY_FOR_DESIGN : Scope approved,\nready for technical design

  READY_FOR_DESIGN --> FEATURE_REJECTED : Majority REJECT votes
  FEATURE_REJECTED : status: FEATURE_REJECTED
  FEATURE_REJECTED : Feature blocked

  note right of READY_FOR_DESIGN
    **AI Auto-generates:**
    design.discussion.md
    (Initial design proposal)
  end note
}

state "Design Stage" as design {
  [*] --> OPEN_D : design.discussion.md created

  OPEN_D : status: OPEN
  OPEN_D : Discuss architecture,\ntech stack, data models

  OPEN_D --> READY_FOR_IMPLEMENTATION : ≥2 READY votes
  READY_FOR_IMPLEMENTATION : status: READY_FOR_IMPLEMENTATION
  READY_FOR_IMPLEMENTATION : Design approved,\nready to implement

  OPEN_D --> DESIGN_REJECTED : Majority REJECT votes
  DESIGN_REJECTED : status: DESIGN_REJECTED
  DESIGN_REJECTED : Design needs rework

  note right of READY_FOR_IMPLEMENTATION
    **AI Auto-generates:**
    implementation.discussion.md
    (Implementation tracking)
  end note
}

state "Implementation Stage" as impl {
  [*] --> IN_PROGRESS : implementation.discussion.md created

  IN_PROGRESS : status: IN_PROGRESS
  IN_PROGRESS : Track tasks,\ncode progress,\nblocking issues

  IN_PROGRESS --> READY_FOR_REVIEW : All tasks completed\n≥2 READY votes

  READY_FOR_REVIEW : status: READY_FOR_REVIEW
  READY_FOR_REVIEW : Implementation complete

  note right of READY_FOR_REVIEW
    **AI Auto-generates:**
    review.discussion.md
    (Code review tracking)
  end note
}

state "Review Stage" as review {
  [*] --> UNDER_REVIEW : review.discussion.md created

  UNDER_REVIEW : status: UNDER_REVIEW
  UNDER_REVIEW : Code review,\ntesting, QA

  UNDER_REVIEW --> APPROVED : ≥2 READY votes
  UNDER_REVIEW --> NEEDS_CHANGES : CHANGES votes

  APPROVED : status: APPROVED
  APPROVED : Ready to merge

  NEEDS_CHANGES --> UNDER_REVIEW : Changes addressed
}

[*] --> feature
READY_FOR_DESIGN --> design
READY_FOR_IMPLEMENTATION --> impl
READY_FOR_REVIEW --> review
APPROVED --> [*]

legend bottom
  **Vote Counting Rules (Configured per stage):**

  promotion_rule:
    allow_agent_votes: false        # Only count human votes
    ready_min_eligible_votes: 2     # Need 2 READY to promote
    reject_min_eligible_votes: 1    # Need 1 REJECT to block

  **Vote Format in Discussion Files:**
  ParticipantName: Comment text. VOTE: READY|CHANGES|REJECT
  AI_BotName: Comment text. VOTE: CHANGES  (excluded if allow_agent_votes: false)

  **Status Transitions:**
  - Automatic when vote thresholds met
  - AI updates YAML header: status: field
  - AI appends consensus comment
  - Triggers next stage discussion creation

  **Example Progression:**
  1. Feature discussion: Define WHAT we're building
  2. Design discussion: Define HOW we'll build it
  3. Implementation discussion: Track building progress
  4. Review discussion: Verify quality before merge
endlegend

note right of feature
  **Participants Use Structured Markers:**
  **DECISION**: Web platform, React frontend
  **QUESTION**: Mobile support in MVP?
  **ACTION**: @Alice research auth options

  These are extracted to .sum.md files
  for easy reference
end note

note right of design
  **Design Decisions Tracked:**
  - Architecture choices
  - Technology stack
  - Data models
  - API contracts
  - Risk trade-offs
end note

note right of impl
  **Implementation Tracking:**
  - Task breakdowns
  - Blocking issues
  - Progress updates
  - Code references
end note

note right of review
  **Review Checklist:**
  - Code quality
  - Test coverage
  - Documentation
  - Performance
  - Security
end note

@enduml