mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-21 07:33:14 +01:00
feat(captain): postmortem template and step, first on #3787; Unverified line in READY and lane reports (GST-805) (#3807)
* test(captain): pin the Unverified line and the postmortem template (GST-805, failing first) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(captain): postmortem template and step; Unverified line in READY and lane reports (GST-805) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix: pre-landing review fixes (GST-805: the lane guide says the lane writes Evidence and Unverified, /ship items 1-4; rewrap the READY contract paragraph) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs: CREW template rules 6-7 and the rule map name the Unverified line (GST-805 docs audit a242-1) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test(archaeology): allow the captain skill to name its postmortem template (GST-805) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(captain): trim Reports and READY-options prose so the merged skill stays under its 6,551-token ceiling (GST-805) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
1 parent
46c9f612c0
commit
15cbc274d9
11 files changed
+188
-49
No files matched your search
+16
-16
@@ -110,13 +110,12 @@ through it to one person (the owner). The operating model below is what keeps do
|
||||
lanes merging into one base branch every day without a red base: lanes never merge, a
|
||||
READY block is the only merge trigger, every merge runs through a train, every decision
|
||||
the owner makes is recorded in their own words, and flakes are fixed daily instead of
|
||||
retried away. The guide for a team setting this up on Capy, with the drive layout and
|
||||
the templates, is `docs/captain.md` in the gstack checkout; the copy-paste files are in
|
||||
`captain/templates/` next to this skill.
|
||||
retried away. The team guide, drive layout included, is `docs/captain.md`; the copy-paste
|
||||
files are in `captain/templates/` next to this skill.
|
||||
|
||||
Usage: `/captain [setup | ready <pr> | train | digest | approvals | flaky-pass]`; `/crew` is
|
||||
the same skill. With no argument, read the crew's rules file and the digest, then do whatever the open item at
|
||||
the top of the digest needs.
|
||||
the same skill. With no argument, read the rules file and the digest, then act on the
|
||||
digest's top open item.
|
||||
|
||||
## Boundaries
|
||||
|
||||
@@ -191,11 +190,10 @@ and adds the lines the tool cannot know. Validate every field before the pin goe
|
||||
| `READY_RECEIPT` | the receipt path the tool wrote (local and on the notes ref) | missing |
|
||||
| flaky cases | each one already in the ledger, with both runs | a rerun that is not logged, or a second failure called a flake |
|
||||
| lane statement | "head frozen from now on" | absent |
|
||||
| `Unverified` | each claim the lane did not check itself, or `none` | never refused or staled; ask for it |
|
||||
|
||||
Optional lines a crew may require in its rules file: the gate run id and tree hash the
|
||||
lane's own gate covered (useful where lanes gate on their own machines), the issue the PR
|
||||
closes, and the key before/after image for the merge ask. Ship the fields as options and
|
||||
let the rules file pick; one crew's habit is not the contract.
|
||||
Optional lines a crew's rules file may require: the gate run id and tree hash of the
|
||||
lane's own gate, the issue the PR closes, and the key before/after image.
|
||||
|
||||
After READY the head is frozen. A push drops the PR from any train and needs a new READY
|
||||
at the new head, /ship rerun included. The one exception is the stamp push below.
|
||||
@@ -416,14 +414,16 @@ occurrence escalates. Every rerun's spend is reported.
|
||||
|
||||
## Reports and waves
|
||||
|
||||
A lane that finishes writes `reports/<code>.md` (`captain/templates/report.md`): Outcome,
|
||||
PR (number, head, version, checks), Needs (what the owner must do), Cost, Lesson, and
|
||||
the Approvals table. The controller reads reports before it reads chat, and turns every
|
||||
Lesson into a rule in the rules file, a line in the standing-rules file
|
||||
(`captain/templates/AGENTS.md`), or a filed tool fix. The controller's own log is
|
||||
append-only and timestamped (`captain/templates/NOTES.md`); the digest is derived from it.
|
||||
A lane that finishes writes `reports/<code>.md` (`captain/templates/report.md`): Outcome
|
||||
with its `Unverified:` line, PR (number, head, version, checks), Needs (what the owner
|
||||
must do), Cost, Lesson, and the Approvals table. The controller reads reports before
|
||||
chat and turns each Lesson into a rule, a standing-rules line (`captain/templates/AGENTS.md`)
|
||||
or a filed tool fix. Its log (`captain/templates/NOTES.md`) is append-only and timestamped;
|
||||
the digest comes from it. After a revert or S1 fix of a merged crew PR, the controller writes a
|
||||
postmortem (`captain/templates/postmortem.md`): why did the lane and every reviewer believe
|
||||
it was right? Its rule change ships as a gstack PR.
|
||||
|
||||
Serial slots cost tens of minutes each, so PRs in one area travel together. When more
|
||||
Serial slots are slow, so PRs in one area travel together. When more
|
||||
than `WAVE_TRIGGER` (6) PRs are READY, run `gstack-ship-queue wave plan` for area groups
|
||||
of 3 to 6, each with an integrator who runs `wave build`, /ship once and READY on the wave
|
||||
PR: one slot, one version. Constituent heads freeze, `--drop` sends a changed one back to
|
||||
|
||||
+16
-16
@@ -38,13 +38,12 @@ through it to one person (the owner). The operating model below is what keeps do
|
||||
lanes merging into one base branch every day without a red base: lanes never merge, a
|
||||
READY block is the only merge trigger, every merge runs through a train, every decision
|
||||
the owner makes is recorded in their own words, and flakes are fixed daily instead of
|
||||
retried away. The guide for a team setting this up on Capy, with the drive layout and
|
||||
the templates, is `docs/captain.md` in the gstack checkout; the copy-paste files are in
|
||||
`captain/templates/` next to this skill.
|
||||
retried away. The team guide, drive layout included, is `docs/captain.md`; the copy-paste
|
||||
files are in `captain/templates/` next to this skill.
|
||||
|
||||
Usage: `/captain [setup | ready <pr> | train | digest | approvals | flaky-pass]`; `/crew` is
|
||||
the same skill. With no argument, read the crew's rules file and the digest, then do whatever the open item at
|
||||
the top of the digest needs.
|
||||
the same skill. With no argument, read the rules file and the digest, then act on the
|
||||
digest's top open item.
|
||||
|
||||
## Boundaries
|
||||
|
||||
@@ -119,11 +118,10 @@ and adds the lines the tool cannot know. Validate every field before the pin goe
|
||||
| `READY_RECEIPT` | the receipt path the tool wrote (local and on the notes ref) | missing |
|
||||
| flaky cases | each one already in the ledger, with both runs | a rerun that is not logged, or a second failure called a flake |
|
||||
| lane statement | "head frozen from now on" | absent |
|
||||
| `Unverified` | each claim the lane did not check itself, or `none` | never refused or staled; ask for it |
|
||||
|
||||
Optional lines a crew may require in its rules file: the gate run id and tree hash the
|
||||
lane's own gate covered (useful where lanes gate on their own machines), the issue the PR
|
||||
closes, and the key before/after image for the merge ask. Ship the fields as options and
|
||||
let the rules file pick; one crew's habit is not the contract.
|
||||
Optional lines a crew's rules file may require: the gate run id and tree hash of the
|
||||
lane's own gate, the issue the PR closes, and the key before/after image.
|
||||
|
||||
After READY the head is frozen. A push drops the PR from any train and needs a new READY
|
||||
at the new head, /ship rerun included. The one exception is the stamp push below.
|
||||
@@ -344,14 +342,16 @@ occurrence escalates. Every rerun's spend is reported.
|
||||
|
||||
## Reports and waves
|
||||
|
||||
A lane that finishes writes `reports/<code>.md` (`captain/templates/report.md`): Outcome,
|
||||
PR (number, head, version, checks), Needs (what the owner must do), Cost, Lesson, and
|
||||
the Approvals table. The controller reads reports before it reads chat, and turns every
|
||||
Lesson into a rule in the rules file, a line in the standing-rules file
|
||||
(`captain/templates/AGENTS.md`), or a filed tool fix. The controller's own log is
|
||||
append-only and timestamped (`captain/templates/NOTES.md`); the digest is derived from it.
|
||||
A lane that finishes writes `reports/<code>.md` (`captain/templates/report.md`): Outcome
|
||||
with its `Unverified:` line, PR (number, head, version, checks), Needs (what the owner
|
||||
must do), Cost, Lesson, and the Approvals table. The controller reads reports before
|
||||
chat and turns each Lesson into a rule, a standing-rules line (`captain/templates/AGENTS.md`)
|
||||
or a filed tool fix. Its log (`captain/templates/NOTES.md`) is append-only and timestamped;
|
||||
the digest comes from it. After a revert or S1 fix of a merged crew PR, the controller writes a
|
||||
postmortem (`captain/templates/postmortem.md`): why did the lane and every reviewer believe
|
||||
it was right? Its rule change ships as a gstack PR.
|
||||
|
||||
Serial slots cost tens of minutes each, so PRs in one area travel together. When more
|
||||
Serial slots are slow, so PRs in one area travel together. When more
|
||||
than `WAVE_TRIGGER` (6) PRs are READY, run `gstack-ship-queue wave plan` for area groups
|
||||
of 3 to 6, each with an integrator who runs `wave build`, /ship once and READY on the wave
|
||||
PR: one slot, one version. Constituent heads freeze, `--drop` sends a changed one back to
|
||||
|
||||
@@ -61,14 +61,15 @@ Homes are paths in the gstack checkout the lane checked at session start.
|
||||
|
||||
6. **Your job ends at an unstamped READY.** Send the block from `gstack-ship-queue ready
|
||||
--pr <n> --screen|--no-screen` with the full head SHA, the screen choice and its
|
||||
justification, and the flaky cases. Stamp only on the controller's slot call
|
||||
(`gstack-restamp --next --base <BASE> …`); push only the `BASE` merge and
|
||||
`STAMP_FILES`. Never merge, never enable auto-merge. Home: `docs/captain.md` (The
|
||||
justification, the flaky cases and the `Unverified:` line. Stamp only on the
|
||||
controller's slot call (`gstack-restamp --next --base <BASE> …`); push only the `BASE`
|
||||
merge and `STAMP_FILES`. Never merge, never enable auto-merge. Home: `docs/captain.md` (The
|
||||
READY contract), `captain/templates/READY.md`, `captain/templates/slot-call.md`,
|
||||
`docs/ship-policy.md` (stamp-at-merge).
|
||||
|
||||
7. **Report.** `reports/<your thread code>.md` in the controller's drive: Outcome, PR,
|
||||
Needs, Cost, Lesson, Approvals. Home: `captain/templates/report.md`.
|
||||
7. **Report.** `reports/<your thread code>.md` in the controller's drive: Outcome (with
|
||||
its `Unverified:` line), PR, Needs, Cost, Lesson, Approvals. Home:
|
||||
`captain/templates/report.md`.
|
||||
|
||||
8. **One path.** Everything goes through `CONTROLLER`, never peer to peer. Home:
|
||||
`docs/captain.md` (Roles, Lane discipline).
|
||||
|
||||
@@ -39,9 +39,17 @@ pin: <sha40> # the full head SHA, restated
|
||||
screen choice: <--no-screen: cases <ids> ran focused and passed | --screen: <reason>>
|
||||
flaky: <none | case, both run ids, logged in the ledger on <date>>
|
||||
review passes: <n> (deferred: <items filed as issues, or none>)
|
||||
Unverified: <none | each claim the lane did not check itself, and why>
|
||||
Head frozen from now on; a push drops this PR from any train and I will READY again.
|
||||
```
|
||||
|
||||
`Unverified:` is required. It lists every claim in the READY that the lane did not check
|
||||
itself: a local test that timed out, a paid run skipped, a number a model reported, a claim
|
||||
inherited from another thread, and a review finding set aside on an assumption nobody
|
||||
tested. `none` means the lane looked for each of these and found none. A missing line is
|
||||
asked for as a follow-up message: it never holds a PR out of a train, does not stale
|
||||
READYs sent before the line existed, and needs no new `ready` or /ship run.
|
||||
|
||||
Optional lines a crew's rules file may require:
|
||||
|
||||
```text
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
# Postmortem: #<n> <one-line title>
|
||||
|
||||
The controller starts one after any revert or S1 fix of a merged crew PR: when that fix's
|
||||
brief goes out, or at the latest when its READY arrives. The controller or a lane it names
|
||||
writes it to `reports/postmortem-<n>.md` in the controller's drive and links it from the
|
||||
fixing PR's body by that path. A revert records what was wrong with the code; this records
|
||||
why everyone who passed it believed it was right. Write it from the record, not from memory
|
||||
and not from the diff alone. Split the reading across read-only subagents when it is long,
|
||||
and keep each section to a table or one short paragraph.
|
||||
|
||||
## What broke
|
||||
|
||||
<what the merged change did wrong, in two or three sentences, with the smallest input that
|
||||
shows it, and the merge commit and version that shipped it>
|
||||
|
||||
## How it was found
|
||||
|
||||
<who or what noticed it, when, and while doing what; whether any gate, check or reviewer
|
||||
caught it, or a person or a sibling lane found it by chance>
|
||||
|
||||
## Impact
|
||||
|
||||
<who was exposed and for how long (merge to fix merge, the versions in between); what is
|
||||
known to have gone wrong; what may have gone wrong and was not checked, said so>
|
||||
|
||||
## Timeline
|
||||
|
||||
| Time (UTC) | Event | Source |
|
||||
|---|---|---|
|
||||
| <time> | <brief, plan, each review pass, READY, merge, discovery, fix, fix merge> | <PR, thread, trail row or run id> |
|
||||
|
||||
## Root cause: why did the lane and every reviewer believe it was right?
|
||||
|
||||
Read first, and mark any item `not retained` when it no longer exists:
|
||||
|
||||
- the PR body and its ship receipt;
|
||||
- every review pass, fix-check, outside-voice and targeted-reader output (the run
|
||||
directory or the lane's subagent transcripts);
|
||||
- the lane's decision trail and its READY, Unverified line included;
|
||||
- the controller's brief, approvals and grants;
|
||||
- earlier PRs, issues or trail rows that met the same problem.
|
||||
|
||||
| Believer | What it was asked | What it checked | What it did not check | Why it passed | Source |
|
||||
|---|---|---|---|---|---|
|
||||
| the controller's brief | <the request> | <…> | <…> | <…> | <message> |
|
||||
| the lane | <the brief> | <its proof and tests> | <the direction it never tested> | <the assumption it held> | <trail row> |
|
||||
| <each review voice, by pass> | <its brief's question> | <…> | <…> | <its words, quoted> | <output> |
|
||||
| tests, pregate, CI, paid gate | <what selected them> | <…> | <the fixture that did not exist> | <…> | <run id> |
|
||||
|
||||
Quote a believer's recorded reason; label anything else `inferred`. A missing record is a
|
||||
finding in its own right: say what it would have shown.
|
||||
|
||||
<then one paragraph: the belief they shared, where it was written down or seen and set
|
||||
aside, and whether the knowledge that would have caught it already existed somewhere the
|
||||
lane did not read>
|
||||
|
||||
## What caught it and what should have
|
||||
|
||||
<what caught it; then the earliest points that should have, cheapest first: a test, a
|
||||
review question, a required replay, a brief that cites an earlier ruling. Name the test or
|
||||
eval that now fails if the change comes back, with its link>
|
||||
|
||||
## Playbook or skill change
|
||||
|
||||
| Change | Home in gstack | Owner | Status | Effectiveness check |
|
||||
|---|---|---|---|---|
|
||||
| <the rule or check> | <file, and the gstack PR or issue> | <lane or controller> | <proposed, PR open, merged> | <what fails or shows up next time> |
|
||||
|
||||
A change kept only in a crew file is a gap. When no rule would have caught it, write
|
||||
`none` and why. The postmortem is done when every row is merged or has an owner.
|
||||
|
||||
## Links
|
||||
|
||||
- Merged PR: #<n> (<merge sha>, <version>)
|
||||
- Revert or fix: #<n>
|
||||
- Issues: <ids>
|
||||
- Threads and trails: <lane thread, fixing thread, decision trail rows>
|
||||
@@ -6,6 +6,8 @@ Written by the lane when it finishes. The controller reads this before chat.
|
||||
|
||||
<what shipped, in two or three sentences; what was out of scope and where it went>
|
||||
|
||||
Unverified: <none | each claim above that the lane did not check itself, and why>
|
||||
|
||||
## PR
|
||||
|
||||
| PR | Head (full SHA) | Version | Checks | Train |
|
||||
|
||||
Reference in new issue
Block a user