mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-05 13:15:24 +02:00
docs: consolidate — roll contributor-mode into CONTRIBUTING, greptile into skills
- docs/contributor-mode.md → merged into CONTRIBUTING.md (session awareness section) - docs/greptile.md → merged into docs/skills.md (Greptile integration section) - Reordered docs table: Skills > Architecture > Browser > Contributing > Changelog Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -54,6 +54,10 @@ the issue, fix it, and open a PR.
|
||||
This is the best way to contribute: fix gstack while doing your real work, in the
|
||||
project where you actually felt the pain.
|
||||
|
||||
### Session awareness
|
||||
|
||||
When you have 3+ gstack sessions open simultaneously, every question tells you which project, which branch, and what's happening. No more staring at a question thinking "wait, which window is this?" The format is consistent across all 13 skills.
|
||||
|
||||
## Working on gstack inside the gstack repo
|
||||
|
||||
When you're editing gstack skills and want to test them by actually using gstack
|
||||
|
||||
@@ -174,12 +174,10 @@ The models are getting better fast. The people who figure out how to work with t
|
||||
|
||||
| Doc | What it covers |
|
||||
|-----|---------------|
|
||||
| [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill |
|
||||
| [Greptile Integration](docs/greptile.md) | PR review triage with [Greptile](https://greptile.com) |
|
||||
| [How to Contribute](docs/contributor-mode.md) | How to help improve gstack |
|
||||
| [Browser Reference](BROWSER.md) | Full command reference for `/browse` |
|
||||
| [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill (includes Greptile integration) |
|
||||
| [Architecture](ARCHITECTURE.md) | Design decisions and system internals |
|
||||
| [Contributing](CONTRIBUTING.md) | Dev setup, testing, and dev mode |
|
||||
| [Browser Reference](BROWSER.md) | Full command reference for `/browse` |
|
||||
| [Contributing](CONTRIBUTING.md) | Dev setup, testing, contributor mode, and dev mode |
|
||||
| [Changelog](CHANGELOG.md) | What's new in every version |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
# Contributor Mode
|
||||
|
||||
gstack is open source. If something annoys you, you can fix it yourself. Contributor mode makes that easier by automatically detecting friction and writing up what went wrong.
|
||||
|
||||
## Enable it
|
||||
|
||||
```
|
||||
gstack-config set gstack_contributor true
|
||||
```
|
||||
|
||||
## How it works
|
||||
|
||||
At the end of each major workflow step, the agent reflects on the gstack tooling it just used. It rates the experience 0-10. If it wasn't a 10, it thinks about why. If there's an obvious, actionable bug or an insightful improvement, it files a **field report** to `~/.gstack/contributor-logs/`.
|
||||
|
||||
Reports include:
|
||||
- What the user/agent was trying to do
|
||||
- What actually happened instead
|
||||
- A 0-10 rating with one-sentence explanation
|
||||
- Steps to reproduce
|
||||
- Raw output (the actual error or unexpected behavior)
|
||||
- "What would make this a 10" — one sentence focusing on the actionable fix
|
||||
|
||||
## Calibration
|
||||
|
||||
The bar is set at real-but-small bugs. Example: `$B js "await fetch(...)"` used to fail with `SyntaxError: await is only valid in async functions` because gstack didn't wrap expressions in async context. The input was reasonable, gstack should have handled it — that's worth filing.
|
||||
|
||||
Things NOT worth filing: your app's bugs, network errors to your URL, auth failures on your site, your own JS logic bugs. Those aren't gstack's fault.
|
||||
|
||||
## What to do with reports
|
||||
|
||||
Browse `~/.gstack/contributor-logs/` periodically. Each report is a self-contained bug report. Fork gstack, fix the issue, and submit a PR. Max 3 reports per session to avoid noise.
|
||||
|
||||
## Session awareness
|
||||
|
||||
When you have 3+ gstack sessions open simultaneously, every question tells you which project, which branch, and what's happening. No more staring at a question thinking "wait, which window is this?"
|
||||
|
||||
Every question — in every skill, even in a single session — states the project and branch, explains the problem in plain English, and gives an opinionated recommendation. The format is consistent across all 13 skills.
|
||||
@@ -1,76 +0,0 @@
|
||||
# Greptile Integration
|
||||
|
||||
[Greptile](https://greptile.com) is a YC company that reviews your PRs automatically. It catches real bugs — race conditions, security issues, things that pass CI and blow up in production. It has genuinely saved my ass more than once. I love these guys.
|
||||
|
||||
## Setup
|
||||
|
||||
Install Greptile on your GitHub repo at [greptile.com](https://greptile.com) — it takes about 30 seconds. Once it's reviewing your PRs, gstack picks up its comments automatically. No additional configuration.
|
||||
|
||||
## How it works
|
||||
|
||||
The problem with any automated reviewer is triage. Greptile is good, but not every comment is a real issue. Some are false positives. Some flag things you already fixed three commits ago. Without a triage layer, the comments pile up and you start ignoring them — which defeats the purpose.
|
||||
|
||||
gstack solves this. `/review` and `/ship` are now Greptile-aware. They read Greptile's comments, classify each one, and take action:
|
||||
|
||||
- **Valid issues** get added to the critical findings and fixed before shipping
|
||||
- **Already-fixed issues** get an auto-reply acknowledging the catch
|
||||
- **False positives** get pushed back — you confirm, and a reply goes out explaining why it's wrong
|
||||
|
||||
The result is a two-layer review: Greptile catches things asynchronously on the PR, then `/review` and `/ship` triage those findings as part of the normal workflow. Nothing falls through the cracks.
|
||||
|
||||
## Learning from history
|
||||
|
||||
Every false positive you confirm gets saved to `~/.gstack/greptile-history.md`. Future runs auto-skip known FP patterns for your codebase. And `/retro` tracks Greptile's batting average over time — so you can see whether the signal-to-noise ratio is improving.
|
||||
|
||||
## Two-tier reply system
|
||||
|
||||
- **Tier 1 (friendly):** First response to a comment. Includes inline diff, explanation, and evidence.
|
||||
- **Tier 2 (firm):** When Greptile re-flags the same issue after a prior reply. Full evidence chain + re-rank request.
|
||||
|
||||
Every reply includes evidence — inline diffs, code references, suggested severity re-ranking. No vague one-line replies.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
You: /ship
|
||||
|
||||
Claude: [syncs main, runs tests, pre-landing review...]
|
||||
|
||||
Greptile found 3 comments on this PR:
|
||||
|
||||
[VALID] app/services/payment_service.rb:47 — Race condition:
|
||||
concurrent charges can double-debit. Recommend DB-level advisory
|
||||
lock around the charge block.
|
||||
→ https://github.com/you/app/pull/42#discussion_r123
|
||||
|
||||
[ALREADY FIXED] app/models/user.rb:12 — Missing null check
|
||||
on email before downcase.
|
||||
→ Already fixed in commit abc1234. Auto-replying.
|
||||
|
||||
[FALSE POSITIVE] lib/auth.rb:88 — "Token comparison should
|
||||
use constant-time comparison." We already use
|
||||
ActiveSupport::SecurityUtils.secure_compare here.
|
||||
→ https://github.com/you/app/pull/42#discussion_r125
|
||||
|
||||
Fixing the race condition in payment_service.rb...
|
||||
Applied advisory lock. Committed: fix: address Greptile
|
||||
review — advisory lock on concurrent charges
|
||||
|
||||
The auth token comment is a false positive — we're already
|
||||
using secure_compare.
|
||||
|
||||
Options for the false positive:
|
||||
A) Reply to Greptile explaining (recommended)
|
||||
B) Fix it anyway
|
||||
C) Ignore
|
||||
|
||||
You: A
|
||||
|
||||
Claude: Replied to Greptile. Re-running tests after the fix...
|
||||
All tests pass. Continuing to version bump.
|
||||
|
||||
[creates PR with Greptile Review section in body]
|
||||
PR: https://github.com/you/app/pull/42
|
||||
```
|
||||
|
||||
Three Greptile comments. One real fix. One auto-acknowledged. One false positive pushed back with a reply. Total extra time: about 30 seconds. And the PR body has the full audit trail.
|
||||
@@ -587,3 +587,63 @@ Claude: Analyzing 21 files changed across 3 commits. Found 8 documentation files
|
||||
```
|
||||
|
||||
It also polishes CHANGELOG voice (without ever overwriting entries), cleans up completed TODOS, checks cross-doc consistency, and asks about VERSION bumps only when appropriate.
|
||||
|
||||
---
|
||||
|
||||
## Greptile integration
|
||||
|
||||
[Greptile](https://greptile.com) is a YC company that reviews your PRs automatically. It catches real bugs — race conditions, security issues, things that pass CI and blow up in production. It has genuinely saved my ass more than once. I love these guys.
|
||||
|
||||
### Setup
|
||||
|
||||
Install Greptile on your GitHub repo at [greptile.com](https://greptile.com) — it takes about 30 seconds. Once it's reviewing your PRs, gstack picks up its comments automatically. No additional configuration.
|
||||
|
||||
### How it works
|
||||
|
||||
The problem with any automated reviewer is triage. Greptile is good, but not every comment is a real issue. Some are false positives. Some flag things you already fixed three commits ago. Without a triage layer, the comments pile up and you start ignoring them — which defeats the purpose.
|
||||
|
||||
gstack solves this. `/review` and `/ship` are now Greptile-aware. They read Greptile's comments, classify each one, and take action:
|
||||
|
||||
- **Valid issues** get added to the critical findings and fixed before shipping
|
||||
- **Already-fixed issues** get an auto-reply acknowledging the catch
|
||||
- **False positives** get pushed back — you confirm, and a reply goes out explaining why it's wrong
|
||||
|
||||
The result is a two-layer review: Greptile catches things asynchronously on the PR, then `/review` and `/ship` triage those findings as part of the normal workflow. Nothing falls through the cracks.
|
||||
|
||||
### Learning from history
|
||||
|
||||
Every false positive you confirm gets saved to `~/.gstack/greptile-history.md`. Future runs auto-skip known FP patterns for your codebase. And `/retro` tracks Greptile's batting average over time — so you can see whether the signal-to-noise ratio is improving.
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
You: /ship
|
||||
|
||||
Claude: [syncs main, runs tests, pre-landing review...]
|
||||
|
||||
Greptile found 3 comments on this PR:
|
||||
|
||||
[VALID] app/services/payment_service.rb:47 — Race condition:
|
||||
concurrent charges can double-debit. Recommend DB-level advisory
|
||||
lock around the charge block.
|
||||
|
||||
[ALREADY FIXED] app/models/user.rb:12 — Missing null check
|
||||
on email before downcase.
|
||||
→ Already fixed in commit abc1234. Auto-replying.
|
||||
|
||||
[FALSE POSITIVE] lib/auth.rb:88 — "Token comparison should
|
||||
use constant-time comparison." We already use
|
||||
ActiveSupport::SecurityUtils.secure_compare here.
|
||||
|
||||
Fixing the race condition in payment_service.rb...
|
||||
|
||||
The auth token comment is a false positive.
|
||||
Options: A) Reply to Greptile explaining B) Fix anyway C) Ignore
|
||||
|
||||
You: A
|
||||
|
||||
Claude: Replied to Greptile. All tests pass.
|
||||
PR: github.com/you/app/pull/42
|
||||
```
|
||||
|
||||
Three Greptile comments. One real fix. One auto-acknowledged. One false positive pushed back with a reply. Total extra time: about 30 seconds.
|
||||
|
||||
Reference in New Issue
Block a user