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.Commentposts to the PR conversation (Issues.CreateComment); nothing creates a review comment atpath+line. - No suggested fix.
ReviewFindingcarriesFile/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.CreateCommentwith{Body, Path, Line, Side: "RIGHT", CommitID}. - Gitea — no direct inline-comment call. Inline comments ride on a submitted
review (
CreatePullReviewwithCommentsand aCOMMENTstate). The Gitea implementation therefore submits a singleCOMMENT-state review carrying the findings, or the capability is simply absent (the type assertion skips it). Decided: implement Gitea as aCOMMENT-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:
- Read the report stashed by
StageReview(tc.ReviewReport, h019.6). - Resolve the head SHA via
PullRequestReader.GetPullRequest(the PR now exists). - 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-8li9remediation direction). - Multi-line suggestions.
- Gitea's "suggested change" rendering: Gitea has no one-click apply, so the
Suggestionthere is informational text in the comment body.
Packages this touches
internal/domain/workflow—ReviewFinding.Suggestion;StagePostReviewComments; theForgersubset gains the writer (orTaskContextgains the writer seam).internal/forge—ReviewCommentWriter, GitHub + Gitea implementations.internal/app/agentworker— the reviewer prompt asks for aSuggestionon confirmed, mechanically-fixable findings;record_findingaccepts it.