# Review Workflow
## 1. Thread model (authoritative)
Each thread is a single `LineComment` with:
- anchor (`file_path`, `old_line`, `new_line`, `side`)
- thread `status` (`open`, `pending`, `addressed`)
- thread `author` (original commenter)
- ordered replies
Replies do not have thread status. A reply event updates the parent thread status.
## 2. Thread status transitions
### Automatic transitions
- New comment created -> `open`
- Reply by original thread author -> `open`
- Reply by different author (including AI in normal flows) -> `pending`
### Manual transitions
- Mark open: original thread author -> `open`
- Mark addressed: original thread author -> `addressed`
- Force mark addressed: force path (no author gate) -> `addressed`
## 3. Review state reconciliation
Review state is reconciled from thread statuses:
- if any thread is `open`, review is `open`
- else if no thread is `open`, review is `under_review`
- `done` is explicit and guarded
`done` guard:
- normal set to `done` fails when unresolved threads (`open` or `pending`) exist
- force done bypasses this check
- if new unresolved activity appears after `done`, review auto-reopens to `open`
## 4. Threading practice
Use line-level comments for actionable feedback. Keep one issue per thread so resolution is obvious.
## 5. Drive thread state deliberately
- Use `open` when code changes are required.
- Use `pending` when a reply is waiting on counterpart action.
- Use `addressed` when the original reviewer confirms resolution.
Example:
- reviewer leaves a comment -> `open`
- author replies "fixed in 9d2b3af" -> `pending`
- reviewer checks the change and is still unhappy -> reply reopens thread to `open`
- reviewer is satisfied -> mark `addressed`
## 6. AI eligibility matrix (what status to use before sending to AI)
Global precondition:
- review must not be `done` (AI session is skipped otherwise)
### Mode = `refactor`
- No explicit `comment_ids` (auto-target):
- processed: `open`
- skipped: `pending`, `addressed`
- Explicit `comment_ids`:
- processed: `open`
- skipped: `pending`, `addressed`
What this means:
- set thread to `open` before running AI refactor
- `pending` or `addressed` threads will not be processed in refactor mode
### Mode = `reply`
- No explicit `comment_ids` (auto-target):
- processed: `open`, `pending`
- skipped: `addressed`
- Explicit `comment_ids`:
- processed: any selected status (including `addressed`)
- skipped by status filter: none
What this means:
- for normal reply runs, use `open` or `pending`
- explicit thread targeting can still send an `addressed` thread to AI reply mode
## 7. Post-AI behavior
- AI output is persisted as a reply in the target thread.
- In typical human-authored threads, this sets thread status to `pending`.
- Review state then reconciles based on resulting thread statuses.
Example:
- thread is `open`
- you press `x` for AI refactor
- AI posts a reply into that thread
- thread becomes `pending`
- you inspect the code and either mark it `addressed` or reopen it
## 8. Refresh after code edits
After code edits or automation runs, refresh in TUI so thread anchors and diff context stay current.
If the TUI was opened with `--commit` or `--base` / `--head`, refresh keeps using that same revision source instead of falling back to the working tree.
## 9. Reviewing historical revisions
Parley can review more than the live working tree:
- `parley tui --commit <rev>`: diff that commit against its first parent
- `parley tui --base <rev>`: diff `<rev>..HEAD`
- `parley tui --base <rev> --head <rev>`: diff an explicit base/head range
- `parley tui --base <rev> --head HEAD`: diff everything after `<rev>`
- `parley tui --base <rev>^ --head HEAD`: diff everything after and including `<rev>`
AI sessions use the same selected revision source for prompt context.
Inside the TUI, `Ctrl+k` opens the command palette. Select `Open Commit Picker` to choose from recent commits, filter by message or SHA, and press `Enter` to apply the selected commit as the active diff source.
Select `Open Review Picker` from the same command palette to switch review context. This reloads comments, replies, and review state from the selected review while keeping the active working tree, commit, or range diff unchanged.
Select `Create Review` to create a new review context from inside the TUI and switch to it immediately. New comments then persist under that review's directory.
Current limitation:
- the revision source is not stored in the review session yet, so a later reopen still needs the same CLI flags.