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:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-04 03:23:51 +00:00
1 parent 46c9f612c0
commit 15cbc274d9
11 files changed
+188 -49

No files matched your search

+16 -16
View File
@@ -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
View File
@@ -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
+6 -5
View File
@@ -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).
+8
View File
@@ -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
+77
View File
@@ -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>
+2
View File
@@ -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 |