review-bot/docs/REVIEW_STRATEGY.md

Review Update Strategy

review-bot uses an edit-in-place strategy for updating reviews. Reviews are never deleted — this preserves conversation threads on inline comments.

State Transition Diagram

stateDiagram-v2
    [*] --> NoExistingReview: First run

    NoExistingReview --> POST_Review: Generate findings + event
    POST_Review --> PostEscalationCheck: event == APPROVED?

    PostEscalationCheck --> Done: No sibling blocks
    PostEscalationCheck --> Supersede_And_Repost: Sibling has REQUEST_CHANGES
    Supersede_And_Repost --> Done: Posted as REQUEST_CHANGES

    [*] --> ExistingReviewFound: Subsequent run (sentinel match)

    ExistingReviewFound --> CheckEscalation: Determine final event
    CheckEscalation --> CompareState: Apply worst-wins if needed

    CompareState --> SameState: existing.state == new event
    CompareState --> StateChange: existing.state != new event

    SameState --> Skip: Body unchanged
    SameState --> PatchBody: Body changed → PATCH in place

    StateChange --> Escalate: APPROVED → REQUEST_CHANGES
    StateChange --> Downgrade: REQUEST_CHANGES → APPROVED

    Escalate --> Supersede: PATCH old body → "Superseded"
    Supersede --> POST_New_RC: POST new REQUEST_CHANGES

    Downgrade --> POST_New_Approve: POST new APPROVED (old stays intact)

    Skip --> Done
    PatchBody --> Done
    POST_New_RC --> Done
    POST_New_Approve --> Done

Rules

Scenario	Action	Reason
No existing review	POST new	First run
Same state, same body	Skip	Nothing changed — preserve threads
Same state, body changed	PATCH body	Update findings without losing threads
APPROVED → REQUEST_CHANGES	Supersede old + POST new	Can always escalate; old APPROVED is no longer valid
REQUEST_CHANGES → APPROVED	POST new APPROVED	Can't edit state; old REQUEST_CHANGES stays as historical record
Sibling has REQUEST_CHANGES (worst-wins)	Escalate to REQUEST_CHANGES	PR must stay blocked if ANY reviewer blocks

Key Constraints

1. Review state is immutable after POST — Gitea has no API to change APPROVED ↔ REQUEST_CHANGES
2. Never delete reviews — Deleting cascades to inline comments and reply threads
3. "Last review per user" wins — Gitea uses the most recent review from a user for merge decisions
4. REQUEST_CHANGES reviews are never touched — Their inline comments and threads are preserved as historical record
5. APPROVED reviews can be superseded — When escalation is needed, mark old as superseded and POST new

Worst-Wins (Shared Token)

When multiple reviewer roles share a token (e.g., sonnet and security both use sonnet-review-bot):

CI Matrix Run:
  sonnet  → REQUEST_CHANGES (findings)
  security → APPROVED (no security issues)
                ↓
  security sees sibling REQUEST_CHANGES
                ↓
  security escalates → REQUEST_CHANGES
                ↓
  PR stays blocked ✓

The first-run case (no existing review to read login from) uses a post-posting fallback: POST APPROVED → check siblings → if blocked, supersede own APPROVED → re-POST as REQUEST_CHANGES.

Edit Mechanism

Reviews are edited via PATCH /repos/{owner}/{repo}/issues/comments/{id}:

• Review body: ID obtained from the timeline API (/issues/{index}/timeline, type "review")
• Inline comments: IDs obtained from /pulls/{index}/reviews/{id}/comments
• Both are editable by the token that created them
• ListReviews always returns the original body (reads from review table, not comment table) — sentinel matching works regardless of edits

Inline Comments Lifecycle

Event	Inline comments behavior
First POST	Created on specific diff lines
PATCH body (same state)	Unchanged — still current findings
Supersede (state change)	Old inline comments stay (readable but on outdated code)
New POST after supersede	Fresh inline comments on current diff