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

5.1 KiB

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

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.