From 0ba14acf3d6bc39c899baf9b1dce9709bb3e72e5 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Fri, 13 Mar 2026 15:26:49 -0700 Subject: [PATCH] feat: add shared Greptile comment triage reference doc Shared reference for fetching, filtering, and classifying Greptile review comments on GitHub PRs. Used by both /review and /ship skills. Includes parallel API fetching, suppressions check, classification logic, reply APIs, and history file writes. --- review/greptile-triage.md | 122 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 review/greptile-triage.md diff --git a/review/greptile-triage.md b/review/greptile-triage.md new file mode 100644 index 00000000..9d26a6b6 --- /dev/null +++ b/review/greptile-triage.md @@ -0,0 +1,122 @@ +# Greptile Comment Triage + +Shared reference for fetching, filtering, and classifying Greptile review comments on GitHub PRs. Both `/review` (Step 2.5) and `/ship` (Step 3.75) reference this document. + +--- + +## Fetch + +Run these commands to detect the PR and fetch comments. Both API calls run in parallel. + +```bash +REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null) +PR_NUMBER=$(gh pr view --json number --jq '.number' 2>/dev/null) +``` + +**If either fails or is empty:** Skip Greptile triage silently. This integration is additive — the workflow works without it. + +```bash +# Fetch line-level review comments AND top-level PR comments in parallel +gh api repos/$REPO/pulls/$PR_NUMBER/comments \ + --jq '.[] | select(.user.login == "greptile-apps[bot]") | select(.position != null) | {id: .id, path: .path, line: .line, body: .body, html_url: .html_url, source: "line-level"}' > /tmp/greptile_line.json & +gh api repos/$REPO/issues/$PR_NUMBER/comments \ + --jq '.[] | select(.user.login == "greptile-apps[bot]") | {id: .id, body: .body, html_url: .html_url, source: "top-level"}' > /tmp/greptile_top.json & +wait +``` + +**If API errors or zero Greptile comments across both endpoints:** Skip silently. + +The `position != null` filter on line-level comments automatically skips outdated comments from force-pushed code. + +--- + +## Suppressions Check + +Read `~/.gstack/greptile-history.md` if it exists. Each line records a previous triage outcome: + +``` + | | | | +``` + +**Categories** (fixed set): `race-condition`, `null-check`, `error-handling`, `style`, `type-safety`, `security`, `performance`, `correctness`, `other` + +Match each fetched comment against entries where: +- `type == fp` (only suppress known false positives, not previously fixed real issues) +- `repo` matches the current repo +- `file-pattern` matches the comment's file path +- `category` matches the issue type in the comment + +Skip matched comments as **SUPPRESSED**. + +If the history file doesn't exist or has unparseable lines, skip those lines and continue — never fail on a malformed history file. + +--- + +## Classify + +For each non-suppressed comment: + +1. **Line-level comments:** Read the file at the indicated `path:line` and surrounding context (±10 lines) +2. **Top-level comments:** Read the full comment body +3. Cross-reference the comment against the full diff (`git diff origin/main`) and the review checklist +4. Classify: + - **VALID & ACTIONABLE** — a real bug, race condition, security issue, or correctness problem that exists in the current code + - **VALID BUT ALREADY FIXED** — a real issue that was addressed in a subsequent commit on the branch. Identify the fixing commit SHA. + - **FALSE POSITIVE** — the comment misunderstands the code, flags something handled elsewhere, or is stylistic noise + - **SUPPRESSED** — already filtered in the suppressions check above + +--- + +## Reply APIs + +When replying to Greptile comments, use the correct endpoint based on comment source: + +**Line-level comments** (from `pulls/$PR/comments`): +```bash +gh api repos/$REPO/pulls/$PR_NUMBER/comments/$COMMENT_ID/replies \ + -f body="" +``` + +**Top-level comments** (from `issues/$PR/comments`): +```bash +gh api repos/$REPO/issues/$PR_NUMBER/comments \ + -f body="" +``` + +**If a reply POST fails** (e.g., PR was closed, no write permission): warn and continue. Do not stop the workflow for a failed reply. + +--- + +## History File Writes + +Before writing, ensure the directory exists: +```bash +mkdir -p ~/.gstack +``` + +Append one line per triage outcome to `~/.gstack/greptile-history.md`: +``` + | | | | +``` + +Example entries: +``` +2026-03-13 | garrytan/myapp | fp | app/services/auth_service.rb | race-condition +2026-03-13 | garrytan/myapp | fix | app/models/user.rb | null-check +2026-03-13 | garrytan/myapp | already-fixed | lib/payments.rb | error-handling +``` + +--- + +## Output Format + +Include a Greptile summary in the output header: +``` ++ N Greptile comments (X valid, Y fixed, Z FP) +``` + +For each classified comment, show: +- Classification tag: `[VALID]`, `[FIXED]`, `[FALSE POSITIVE]`, `[SUPPRESSED]` +- File:line reference (for line-level) or `[top-level]` (for top-level) +- One-line body summary +- Permalink URL (the `html_url` field)