gstack/review/greptile-triage.md

# 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:

```
<date> | <repo> | <type:fp|fix|already-fixed> | <file-pattern> | <category>
```

**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="<reply text>"
```

**Top-level comments** (from `issues/$PR/comments`):
```bash
gh api repos/$REPO/issues/$PR_NUMBER/comments \
  -f body="<reply text>"
```

**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`:
```
<YYYY-MM-DD> | <owner/repo> | <type> | <file-pattern> | <category>
```

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)