Files
archie/docs/prds/inline-review.md
T

116 lines
5.1 KiB
Markdown

# Inline review -- decision
**Status:** Proposed
**Beads issue:** `archie-core-q9au`
**Builds on:** `archie-core-h019` (adversarial self-review), `docs/architecture/adversarial-review.md`
## Problem
Findings reach the operator only as a flat list in the PR body
(`renderPRReviewSection`, h019.6): `` - `file.go:12` (confirmed, error): <defect>
— <scenario> ``. That is a report *about* the code, not a review *of* it. A real
reviewer anchors each finding to the line it is about, so the author sees it in
context — and, when the fix is mechanical, attaches the replacement so it can be
applied in one click.
Both halves are missing today:
- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR
*conversation* (`Issues.CreateComment`); nothing creates a review comment at
`path` + `line`.
- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/
`FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even
an anchored comment could only describe the fix, not offer it.
## Decisions
### 1. A narrow, type-asserted write surface
```go
type ReviewCommentWriter interface {
CreateReviewComment(ctx context.Context, owner, repo string, number int,
commitID, path string, line int, body string) error
}
```
Type-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge
that cannot do it is skipped rather than faked.
Per-forge reality (verified against the SDKs, 2026-09-11):
- **GitHub** — direct: `PullRequests.CreateComment` with
`{Body, Path, Line, Side: "RIGHT", CommitID}`.
- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted
review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea
implementation therefore submits a single `COMMENT`-state review carrying the
findings, or the capability is simply absent (the type assertion skips it).
Decided: implement Gitea as a `COMMENT`-state review; do not block the feature
on it.
### 2. `Suggestion`, and only on confirmed findings
`ReviewFinding` gains an optional `Suggestion string` — the replacement text for
the anchored line, rendered as a fenced `suggestion` block (GitHub's one-click
"Commit suggestion").
**Only `confirmed` findings may carry one.** A wrong suggestion is a
one-click path to breaking code a reviewer then has to notice; `confirmed` is by
definition the verdict the reviewer traced and can state the failure for. A
`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is
the h019.5 calibration rule reused, not a new one.
`Suggestion` replaces the anchored line exactly. Single-line only in this cut;
multi-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a
multi-line suggestion that is off by one line silently corrupts the file.
### 3. Which findings are posted inline
Only findings that are **line-anchored** (`Line > 0`). A whole-file finding
(`Line == 0`, e.g. "README.md is stale") has no line to attach to and stays in
the PR-body list. The body section keeps listing everything, so it remains the
complete record and the fallback.
Findings that block never reach this path: a surviving blocking finding parks
the task before `StageOpenPR`, so there is no PR to comment on. Inline comments
are the non-blocking, line-anchored subset — which is exactly the set that would
otherwise be a body-only list the author has to map back to lines by hand.
### 4. A best-effort stage after `StageOpenPR`
New `StagePostReviewComments`, after `StageOpenPR`:
1. Read the report stashed by `StageReview` (`tc.ReviewReport`, h019.6).
2. Resolve the head SHA via `PullRequestReader.GetPullRequest` (the PR now
exists).
3. Post each line-anchored finding as an inline comment, with a suggestion block
when `Verdict == confirmed && Suggestion != ""`.
**Failures log and never fail the task.** The PR is already open; a comment that
failed to post must not park a task whose actual work succeeded, and the body
section already carries every finding. This mirrors `OpenPR`'s existing
best-effort `LinkBranch` call.
### 5. No separate opt-in flag (for now)
Inline comments are posted whenever a review ran and produced line-anchored
findings — the same `repo.review_enabled` gate already covers it. A second flag
is a knob to add if it proves noisy in practice; adding it speculatively is the
smallest-change principle's opposite.
## Out of scope
- Commenting on the blocking/parked case (no PR exists).
- Resolving/dismissing threads, or reacting to replies (that is the
`archie-core-8li9` remediation direction).
- Multi-line suggestions.
- Gitea's "suggested change" rendering: Gitea has no one-click apply, so the
`Suggestion` there is informational text in the comment body.
## Packages this touches
- `internal/domain/workflow` — `ReviewFinding.Suggestion`; `StagePostReviewComments`;
the `Forger` subset gains the writer (or `TaskContext` gains the writer seam).
- `internal/forge` — `ReviewCommentWriter`, GitHub + Gitea implementations.
- `internal/app/agentworker` — the reviewer prompt asks for a `Suggestion` on
confirmed, mechanically-fixable findings; `record_finding` accepts it.