Skip to content

Add guides for landing a fix in someone else's repo and running human playtests (GST-2757) - #4380

Merged
capy-ai[bot] merged 2 commits into
mainfrom
guides-for-outside-fixes-and-playtests
Nov 16, 2026
Merged

capy-ai[bot] merged 2 commits into
mainfrom
guides-for-outside-fixes-and-playtests

Conversation

@garrytan

@garrytan garrytan commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Adds two short how-to guides: landing a fix in a repository you don't own, and running a human playtest.
Why: both habits kept coming up in our own agent teams, and gstack had no page for either.
Nothing to do as a reader; the pages are in docs/ and change no skill or tool.

Agent notes

What's in it. docs/howto-land-a-fix-in-someone-elses-repo.md: read their rules, search their main and open PRs for the same fix before designing, read the code's history, keep it small, run every guard their CI runs before opening, answer each review point in a new commit and rerun the proof. docs/howto-run-human-playtests.md: vendor-free; ask about moments and where people would stop, and never pick a winner by having people play two builds back to back, because the order played decided the pick. Plus a changelog fragment.

Evidence is thin, said plainly. Guide 1 rests on one outside repository: the first PR there failed its first review on a CI guard that was never run locally, and a maintainer's much smaller fix merged over a far larger one. Guide 2 rests on one team's playtests, where the build played second won most back-to-back picks whichever build it was. Neither figure was re-checked for this PR.

Why add it, and how we'll know (ETHOS 9, Earn Its Place). Stated reason: both lessons cost real review rounds and a wasted test series. Measure, as the follow-up: count review rounds on the next two outside PRs that use guide 1, and use guide 2 on the next playtest and record whether a decision came from quit points and moments rather than a pick.

Docs-only. bin/gstack-docs-only --base origin/main --head HEAD prints DOCS_ONLY: yes (3 file(s); ...). A README index row would make the PR non-docs-only (README.md is named by workflows and CLAUDE.md), so the index rows are left for a follow-up.

Pre-Landing Review

Pre-Landing Review: 1 issues — 0 auto-fixed, 0 asked (0 fixed, 0 skipped), 0 deferred, 1 noted
REVIEW_LOOP: passes=1 blocking_found=0 deferred=0 noted=1 fixed=0 scope=frozen ledgers_read=1
Gate edits: none detected (0 listed, 0 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)

Review plan: class=docs, depth light, one pass on the whole diff, no dispatched readers (specialists, red team, adversarial and second-model review skipped by the plan for a docs-class change with no numbers).

Review notes

Below the blocking floor; recorded here and not fixed in this PR.

  • INFORMATIONAL README.md:270 The two new how-to guides are not listed in README.md's how-to table, so readers browsing the README won't find them. Left open on purpose: README.md would make this PR non-docs-only.

Documentation

Status: blocked under an accepted exception. Scope: docs/ and README.md, base 0326b14 to head b767f44. The audit found both new guides and the changelog fragment current; it added README.md how-to rows, which were reverted to keep the PR docs-only.
Documentation exception: accepted by GStack Minder lane GSTA-554 (parent of this /ship run) 2026-11-15 via parent agent message to the /ship subagent, 2026-11-15: Leave the README index note as an open note; the PR stays docs-only on purpose.

Test plan

  • Docs lane (bun test on the 8 docs-lane files gstack-docs-only names): 62 tests ran, 0 failed

Approvals

No approvals recorded for branch guides-for-outside-fixes-and-playtests.
Plan: exempt: crew:R81

Refs GST-2757
Closes GST-2757 on merge.

{
  "schema_version": 1,
  "pr": 4380,
  "head": "b767f44829cdc4a20a0eeb14ee33ef8897d24067",
  "version": "1.99.5.0",
  "base": "main",
  "gate": {
    "docs": {
      "pass": 62,
      "fail": 0,
      "skip": 0
    }
  },
  "session_kind": "unattended",
  "head_tree": "f5671023202104fc4243df81accda5aea5e1d6af",
  "product_patch_id": "cb8e3ebd56d52e68d994371e0b4dac945b2107cf",
  "gstack_version": "1.99.5.0",
  "review_depth": {
    "depth": "light",
    "class": "docs",
    "runtime_lines": 0,
    "rules": "66e5174161eecc2c",
    "base": "0326b144af36676d599dcf63a9fad9a870d22ed6",
    "registry": "0326b144af36676d599dcf63a9fad9a870d22ed6",
    "gate_scan": {
      "tagged": 0,
      "head": "b767f44829cdc4a20a0eeb14ee33ef8897d24067"
    },
    "reasons": [
      "runtime=0"
    ],
    "risk": [],
    "mode": "panel"
  },
  "pregate": "pass @f56710232021 (8 checks, current for b767f44829cd)",
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "blocked",
    "scope": "docs/ and README.md (base 0326b144 to head b767f448); the two new guides and the changelog fragment are current, README.md's how-to table does not list the new guides",
    "exception": {
      "accepted_by": "GStack Minder lane GSTA-554 (parent of this /ship run)",
      "date": "2026-11-15",
      "via": "parent agent message to the /ship subagent, 2026-11-15",
      "reason": "Leave the README index note as an open note; the PR stays docs-only on purpose."
    }
  },
  "review_loop": {
    "passes": 1,
    "blocking_found": 0,
    "deferred": 0,
    "noted": 1,
    "fixed": 0,
    "scope": "frozen",
    "rounds": 1,
    "ledgers_read": 1
  },
  "gate_dispositions": []
}

Open in Capy

… playtests (GST-2757)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@trunk-io

trunk-io Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@capy-ai
capy-ai Bot merged commit 984a268 into main Nov 16, 2026
43 checks passed
capy-ai Bot added a commit that referenced this pull request Nov 17, 2026
- /autoplan's approval page no longer hides a reviewer's product objection behind "keep your direction". (#4431)
- Every skill that loads the shared preamble, on every host, now says to ask a question once and to check a file before handing it over. (#4383)
- The Captain manuals now name the `Failed or skipped:` and `Also changed:` lines that READY and lane reports carry. (#4432)
- gstack's shell locks hold again on Ubuntu 26.04, where `mkdir` reports success when another process won the race (GST-2247). (#4262)
- `test/gstack-lock-race.test.ts` runs the old pattern and the helper against a PATH shim that behaves like uutils 0.8.0 `mkdir`, so it runs on any runner image: the old pattern lets two of four racers win, the helper admits exactly one in each of 60 races and never overlaps across take, hold and release loops, and parallel `gstack-config` writers keep every key. (#4262)
- Windows Setup E2E now runs when `bin/gstack-lock.sh` changes. (#4433)
- Claude Code's skill list now says when to use each gstack skill, so Opus loads /review and /plan-eng-review when a request fits. (#4387)
- A pull request's merge head can no longer keep its `/ship` receipt without a full review. (#4365)
- `/ship` now counts review rounds per pull request, and the head that merges always gets a full review. (#4360)
- /ship's documentation audit no longer accepts a passing result when an earlier line from the same audit said "blocked". (#4434)
- /ship's documentation audit no longer spends an attempt when the audit child writes text after its result. (#4285)
- The README lists the two new guides, and the install doc counts its hooks right. (#4403)
- docs/releases.md now says the stable release cut treats a failed commit status as red and a pending one as still going, as it has since #4257. (#4436)
- /ship's `finish --docs-requested` now accepts a docs fix when the audit named the file with a line number. (#4437)
- Document the `.gstack/approval-classes.json` schema, `gstack-approval-classes` CLI commands, and owner approval citation format in `docs/ship-policy.md#approval-classes`. (#4355)
- `/eval-plan` now runs four result checks instead of leaving them to judgment. (#4384)
- The /review coverage-audit eval no longer fails a run that really read the source file when zsh stops a command line at an `echo ====` separator. (#4364)
- Sixteen in-repo documentation links reach their section again. (#4394)
- gstack agents now open every status report with what failed, what they didn't verify and what else they changed. (#4273)
- Two new short guides. (#4380)
- A skill you wrote whose contract still lists `check_after_last_edit` keeps the rest of its contract. (#4439)
- The ship policy guide now explains how to merge any pull request with `gstack-ship-queue land`, even in a repository with one maintainer. (#4377)
- /ship's test step runs a large unit suite on Linux. (#4426)
- Every skill that loads the shared preamble, on every host, now says never to print a whole environment, git config or process table. (#4382)
- Pull requests from /ship now open with at most three plain lines, and every merge lands as one commit titled with the PR title. (#4438)
- `gstack-pr-wait`, `gstack-ci-gate` and the release cut no longer call a commit green while a check on it failed. (#4257)
- `gstack-runaway` now says what a thread's cold and empty wakes cost, not just how many there were (GST-2770). (#4385)
- The optional Stop hook no longer checks for a test run after the last edit, and /verify asks for it in plain words instead. (#4428)
- /ship's test step says when it ran out of time, and you can set its budget. (#4429)
- The remote test command no longer puts every file on one command line. (#4429)
- The stable release no longer waits on the nightly Windows tests (GST-2815). (#4400)
- Ubicloud fan-outs can no longer overshoot the vCPU limit, and owners no longer delete each other's VMs. (#4430)
- hono is pinned to 4.13.16, which fixes five advisories the weekly OSV scan found in 4.13.13 (gstack#4406). (#4408)
- `package.json` overrides (#4408)
- `test/dependency-security.test.ts`: the lockfile floor check now covers `hono >= 4.13.16`. (#4408)
- The nightly Windows test run finishes again. (#4409)
- A short write-up checklist in ETHOS.md. (#4381)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant