mirror of
https://github.com/garrytan/gstack.git
synced 2026-07-09 09:38:09 +02:00
feat: TODOS-aware skills, 2-tier Greptile replies, gitignore fix (#61)
* fix: log non-ENOENT errors in ensureStateDir() instead of silently swallowing
Replace bare catch {} with ENOENT-only silence. Non-ENOENT errors (EACCES,
ENOSPC) are now logged to .gstack/browse-server.log. Includes test for
permission-denied scenario with chmod 444.
* feat: merge TODO.md + TODOS.md into unified backlog with shared format reference
Merge TODO.md (roadmap) and TODOS.md (near-term) into one file organized by
skill/component with P0-P4 priority ordering and Completed section. Add shared
review/TODOS-format.md for canonical format. Add static validation tests.
* feat: add 2-tier Greptile reply system with escalation detection
Add reply templates (Tier 1 friendly, Tier 2 firm), explicit escalation
detection algorithm, and severity re-ranking guidance to greptile-triage.md.
* feat: cross-skill TODOS awareness + Greptile template refs in all skills
/ship Step 5.5: auto-detect completed TODOs, offer reorganization.
/review Step 5.5: cross-reference PR against open TODOs.
/plan-ceo-review, /plan-eng-review: TODOS context in planning.
/retro: Backlog Health metric. /qa: bug TODO context in diff-aware mode.
All Greptile-aware skills now reference reply templates and escalation detection.
* chore: bump version and changelog (v0.3.8)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: update CONTRIBUTING.md for v0.3.8 changes
Clarify test tier cost table (Tier 3 standalone vs combined), add TODOS.md
to "Things to know", mention Greptile triage in ship workflow description.
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
+21
-6
@@ -49,7 +49,7 @@ Read `.claude/skills/review/checklist.md`.
|
||||
|
||||
## Step 2.5: Check for Greptile review comments
|
||||
|
||||
Read `.claude/skills/review/greptile-triage.md` and follow the fetch, filter, and classify steps.
|
||||
Read `.claude/skills/review/greptile-triage.md` and follow the fetch, filter, classify, and **escalation detection** steps.
|
||||
|
||||
**If no PR exists, `gh` fails, API returns an error, or there are zero Greptile comments:** Skip this step silently. Greptile integration is additive — the review works without it.
|
||||
|
||||
@@ -95,7 +95,9 @@ After outputting your own findings, if Greptile comments were classified in Step
|
||||
|
||||
**Include a Greptile summary in your output header:** `+ N Greptile comments (X valid, Y fixed, Z FP)`
|
||||
|
||||
1. **VALID & ACTIONABLE comments:** These are already included in your CRITICAL findings — they follow the same AskUserQuestion flow (A: Fix it now, B: Acknowledge, C: False positive). If the user chooses C (false positive), post a reply using the appropriate API from the triage doc and save the pattern to both per-project and global greptile-history (see greptile-triage.md for write details).
|
||||
Before replying to any comment, run the **Escalation Detection** algorithm from greptile-triage.md to determine whether to use Tier 1 (friendly) or Tier 2 (firm) reply templates.
|
||||
|
||||
1. **VALID & ACTIONABLE comments:** These are already included in your CRITICAL findings — they follow the same AskUserQuestion flow (A: Fix it now, B: Acknowledge, C: False positive). If the user chooses A (fix), reply using the **Fix reply template** from greptile-triage.md (include inline diff + explanation). If the user chooses C (false positive), reply using the **False Positive reply template** (include evidence + suggested re-rank), save to both per-project and global greptile-history.
|
||||
|
||||
2. **FALSE POSITIVE comments:** Present each one via AskUserQuestion:
|
||||
- Show the Greptile comment: file:line (or [top-level]) + body summary + permalink URL
|
||||
@@ -105,19 +107,32 @@ After outputting your own findings, if Greptile comments were classified in Step
|
||||
- B) Fix it anyway (if low-effort and harmless)
|
||||
- C) Ignore — don't reply, don't fix
|
||||
|
||||
If the user chooses A, post a reply using the appropriate API from the triage doc and save the pattern to both per-project and global greptile-history (see greptile-triage.md for write details).
|
||||
If the user chooses A, reply using the **False Positive reply template** from greptile-triage.md (include evidence + suggested re-rank), save to both per-project and global greptile-history.
|
||||
|
||||
3. **VALID BUT ALREADY FIXED comments:** Reply acknowledging the catch — no AskUserQuestion needed:
|
||||
- Post reply: `"Good catch — already fixed in <commit-sha>."`
|
||||
- Save to both per-project and global greptile-history (see greptile-triage.md for write details)
|
||||
3. **VALID BUT ALREADY FIXED comments:** Reply using the **Already Fixed reply template** from greptile-triage.md — no AskUserQuestion needed:
|
||||
- Include what was done and the fixing commit SHA
|
||||
- Save to both per-project and global greptile-history
|
||||
|
||||
4. **SUPPRESSED comments:** Skip silently — these are known false positives from previous triage.
|
||||
|
||||
---
|
||||
|
||||
## Step 5.5: TODOS cross-reference
|
||||
|
||||
Read `TODOS.md` in the repository root (if it exists). Cross-reference the PR against open TODOs:
|
||||
|
||||
- **Does this PR close any open TODOs?** If yes, note which items in your output: "This PR addresses TODO: <title>"
|
||||
- **Does this PR create work that should become a TODO?** If yes, flag it as an informational finding.
|
||||
- **Are there related TODOs that provide context for this review?** If yes, reference them when discussing related findings.
|
||||
|
||||
If TODOS.md doesn't exist, skip this step silently.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Read the FULL diff before commenting.** Do not flag issues already addressed in the diff.
|
||||
- **Read-only by default.** Only modify files if the user explicitly chooses "Fix it now" on a critical issue. Never commit, push, or create PRs.
|
||||
- **Be terse.** One line problem, one line fix. No preamble.
|
||||
- **Only flag real problems.** Skip anything that's fine.
|
||||
- **Use Greptile reply templates from greptile-triage.md.** Every reply includes evidence. Never post vague replies.
|
||||
|
||||
+21
-6
@@ -40,7 +40,7 @@ Read `.claude/skills/review/checklist.md`.
|
||||
|
||||
## Step 2.5: Check for Greptile review comments
|
||||
|
||||
Read `.claude/skills/review/greptile-triage.md` and follow the fetch, filter, and classify steps.
|
||||
Read `.claude/skills/review/greptile-triage.md` and follow the fetch, filter, classify, and **escalation detection** steps.
|
||||
|
||||
**If no PR exists, `gh` fails, API returns an error, or there are zero Greptile comments:** Skip this step silently. Greptile integration is additive — the review works without it.
|
||||
|
||||
@@ -86,7 +86,9 @@ After outputting your own findings, if Greptile comments were classified in Step
|
||||
|
||||
**Include a Greptile summary in your output header:** `+ N Greptile comments (X valid, Y fixed, Z FP)`
|
||||
|
||||
1. **VALID & ACTIONABLE comments:** These are already included in your CRITICAL findings — they follow the same AskUserQuestion flow (A: Fix it now, B: Acknowledge, C: False positive). If the user chooses C (false positive), post a reply using the appropriate API from the triage doc and save the pattern to both per-project and global greptile-history (see greptile-triage.md for write details).
|
||||
Before replying to any comment, run the **Escalation Detection** algorithm from greptile-triage.md to determine whether to use Tier 1 (friendly) or Tier 2 (firm) reply templates.
|
||||
|
||||
1. **VALID & ACTIONABLE comments:** These are already included in your CRITICAL findings — they follow the same AskUserQuestion flow (A: Fix it now, B: Acknowledge, C: False positive). If the user chooses A (fix), reply using the **Fix reply template** from greptile-triage.md (include inline diff + explanation). If the user chooses C (false positive), reply using the **False Positive reply template** (include evidence + suggested re-rank), save to both per-project and global greptile-history.
|
||||
|
||||
2. **FALSE POSITIVE comments:** Present each one via AskUserQuestion:
|
||||
- Show the Greptile comment: file:line (or [top-level]) + body summary + permalink URL
|
||||
@@ -96,19 +98,32 @@ After outputting your own findings, if Greptile comments were classified in Step
|
||||
- B) Fix it anyway (if low-effort and harmless)
|
||||
- C) Ignore — don't reply, don't fix
|
||||
|
||||
If the user chooses A, post a reply using the appropriate API from the triage doc and save the pattern to both per-project and global greptile-history (see greptile-triage.md for write details).
|
||||
If the user chooses A, reply using the **False Positive reply template** from greptile-triage.md (include evidence + suggested re-rank), save to both per-project and global greptile-history.
|
||||
|
||||
3. **VALID BUT ALREADY FIXED comments:** Reply acknowledging the catch — no AskUserQuestion needed:
|
||||
- Post reply: `"Good catch — already fixed in <commit-sha>."`
|
||||
- Save to both per-project and global greptile-history (see greptile-triage.md for write details)
|
||||
3. **VALID BUT ALREADY FIXED comments:** Reply using the **Already Fixed reply template** from greptile-triage.md — no AskUserQuestion needed:
|
||||
- Include what was done and the fixing commit SHA
|
||||
- Save to both per-project and global greptile-history
|
||||
|
||||
4. **SUPPRESSED comments:** Skip silently — these are known false positives from previous triage.
|
||||
|
||||
---
|
||||
|
||||
## Step 5.5: TODOS cross-reference
|
||||
|
||||
Read `TODOS.md` in the repository root (if it exists). Cross-reference the PR against open TODOs:
|
||||
|
||||
- **Does this PR close any open TODOs?** If yes, note which items in your output: "This PR addresses TODO: <title>"
|
||||
- **Does this PR create work that should become a TODO?** If yes, flag it as an informational finding.
|
||||
- **Are there related TODOs that provide context for this review?** If yes, reference them when discussing related findings.
|
||||
|
||||
If TODOS.md doesn't exist, skip this step silently.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Read the FULL diff before commenting.** Do not flag issues already addressed in the diff.
|
||||
- **Read-only by default.** Only modify files if the user explicitly chooses "Fix it now" on a critical issue. Never commit, push, or create PRs.
|
||||
- **Be terse.** One line problem, one line fix. No preamble.
|
||||
- **Only flag real problems.** Skip anything that's fine.
|
||||
- **Use Greptile reply templates from greptile-triage.md.** Every reply includes evidence. Never post vague replies.
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
# TODOS.md Format Reference
|
||||
|
||||
Shared reference for the canonical TODOS.md format. Referenced by `/ship` (Step 5.5) and `/plan-ceo-review` (TODOS.md updates section) to ensure consistent TODO item structure.
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```markdown
|
||||
# TODOS
|
||||
|
||||
## <Skill/Component> ← e.g., ## Browse, ## Ship, ## Review, ## Infrastructure
|
||||
<items sorted P0 first, then P1, P2, P3, P4>
|
||||
|
||||
## Completed
|
||||
<finished items with completion annotation>
|
||||
```
|
||||
|
||||
**Sections:** Organize by skill or component (`## Browse`, `## Ship`, `## Review`, `## QA`, `## Retro`, `## Infrastructure`). Within each section, sort items by priority (P0 at top).
|
||||
|
||||
---
|
||||
|
||||
## TODO Item Format
|
||||
|
||||
Each item is an H3 under its section:
|
||||
|
||||
```markdown
|
||||
### <Title>
|
||||
|
||||
**What:** One-line description of the work.
|
||||
|
||||
**Why:** The concrete problem it solves or value it unlocks.
|
||||
|
||||
**Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
|
||||
|
||||
**Effort:** S / M / L / XL
|
||||
**Priority:** P0 / P1 / P2 / P3 / P4
|
||||
**Depends on:** <prerequisites, or "None">
|
||||
```
|
||||
|
||||
**Required fields:** What, Why, Context, Effort, Priority
|
||||
**Optional fields:** Depends on, Blocked by
|
||||
|
||||
---
|
||||
|
||||
## Priority Definitions
|
||||
|
||||
- **P0** — Blocking: must be done before next release
|
||||
- **P1** — Critical: should be done this cycle
|
||||
- **P2** — Important: do when P0/P1 are clear
|
||||
- **P3** — Nice-to-have: revisit after adoption/usage data
|
||||
- **P4** — Someday: good idea, no urgency
|
||||
|
||||
---
|
||||
|
||||
## Completed Item Format
|
||||
|
||||
When an item is completed, move it to the `## Completed` section preserving its original content and appending:
|
||||
|
||||
```markdown
|
||||
**Completed:** vX.Y.Z (YYYY-MM-DD)
|
||||
```
|
||||
@@ -93,6 +93,92 @@ gh api repos/$REPO/issues/$PR_NUMBER/comments \
|
||||
|
||||
---
|
||||
|
||||
## Reply Templates
|
||||
|
||||
Use these templates for every Greptile reply. Always include concrete evidence — never post vague replies.
|
||||
|
||||
### Tier 1 (First response) — Friendly, evidence-included
|
||||
|
||||
**For FIXES (user chose to fix the issue):**
|
||||
|
||||
```
|
||||
**Fixed** in `<commit-sha>`.
|
||||
|
||||
\`\`\`diff
|
||||
- <old problematic line(s)>
|
||||
+ <new fixed line(s)>
|
||||
\`\`\`
|
||||
|
||||
**Why:** <1-sentence explanation of what was wrong and how the fix addresses it>
|
||||
```
|
||||
|
||||
**For ALREADY FIXED (issue addressed in a prior commit on the branch):**
|
||||
|
||||
```
|
||||
**Already fixed** in `<commit-sha>`.
|
||||
|
||||
**What was done:** <1-2 sentences describing how the existing commit addresses this issue>
|
||||
```
|
||||
|
||||
**For FALSE POSITIVES (the comment is incorrect):**
|
||||
|
||||
```
|
||||
**Not a bug.** <1 sentence directly stating why this is incorrect>
|
||||
|
||||
**Evidence:**
|
||||
- <specific code reference showing the pattern is safe/correct>
|
||||
- <e.g., "The nil check is handled by `ActiveRecord::FinderMethods#find` which raises RecordNotFound, not nil">
|
||||
|
||||
**Suggested re-rank:** This appears to be a `<style|noise|misread>` issue, not a `<what Greptile called it>`. Consider lowering severity.
|
||||
```
|
||||
|
||||
### Tier 2 (Greptile re-flags after prior reply) — Firm, overwhelming evidence
|
||||
|
||||
Use Tier 2 when escalation detection (below) identifies a prior GStack reply on the same thread. Include maximum evidence to close the discussion.
|
||||
|
||||
```
|
||||
**This has been reviewed and confirmed as [intentional/already-fixed/not-a-bug].**
|
||||
|
||||
\`\`\`diff
|
||||
<full relevant diff showing the change or safe pattern>
|
||||
\`\`\`
|
||||
|
||||
**Evidence chain:**
|
||||
1. <file:line permalink showing the safe pattern or fix>
|
||||
2. <commit SHA where it was addressed, if applicable>
|
||||
3. <architecture rationale or design decision, if applicable>
|
||||
|
||||
**Suggested re-rank:** Please recalibrate — this is a `<actual category>` issue, not `<claimed category>`. [Link to specific file change permalink if helpful]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Escalation Detection
|
||||
|
||||
Before composing a reply, check if a prior GStack reply already exists on this comment thread:
|
||||
|
||||
1. **For line-level comments:** Fetch replies via `gh api repos/$REPO/pulls/$PR_NUMBER/comments/$COMMENT_ID/replies`. Check if any reply body contains GStack markers: `**Fixed**`, `**Not a bug.**`, `**Already fixed**`.
|
||||
|
||||
2. **For top-level comments:** Scan the fetched issue comments for replies posted after the Greptile comment that contain GStack markers.
|
||||
|
||||
3. **If a prior GStack reply exists AND Greptile posted again on the same file+category:** Use Tier 2 (firm) templates.
|
||||
|
||||
4. **If no prior GStack reply exists:** Use Tier 1 (friendly) templates.
|
||||
|
||||
If escalation detection fails (API error, ambiguous thread): default to Tier 1. Never escalate on ambiguity.
|
||||
|
||||
---
|
||||
|
||||
## Severity Assessment & Re-ranking
|
||||
|
||||
When classifying comments, also assess whether Greptile's implied severity matches reality:
|
||||
|
||||
- If Greptile flags something as a **security/correctness/race-condition** issue but it's actually a **style/performance** nit: include `**Suggested re-rank:**` in the reply requesting the category be corrected.
|
||||
- If Greptile flags a low-severity style issue as if it were critical: push back in the reply.
|
||||
- Always be specific about why the re-ranking is warranted — cite code and line numbers, not opinions.
|
||||
|
||||
---
|
||||
|
||||
## History File Writes
|
||||
|
||||
Before writing, ensure both directories exist:
|
||||
|
||||
Reference in New Issue
Block a user