Commit c038157
authored
docs: make Stage -1 claim explicit and add G4 enforcement-layer check (#37)
## Summary
Two Round-1 QA discipline fixes found by a `/retro` pass: make the Stage
-1 claim read as an imperative first action in SKILL.md, and add a
Guardrails check for enforcement layers on a request path.
## Came from
`/retro` session on 2026-07-23: `9beb8958-4776-4083-a5a7-b77ba29a5029`
### Finding 1 — A6/B15, claim step not firing
- **Symptom:** An agent ran Round-1 QA on one ticket and implementation
on a second while both stayed `Unassigned`, until the user challenged
it: *"why did not assign the ticket to me when you are working on it?
should be clearly stated in your rules!"*
- **Cause:** `references/lifecycle.md` §Stage -1 is correct and has a
proper assignee decision table, but SKILL.md compressed it into a single
bullet carrying three separate rules. The agent read SKILL.md and never
opened the reference.
- **Required behavior:** Claiming is the first tool call of a QA pass,
before Stage 0 discovery.
- **Change:** SKILL.md only. The reference file was already right, so
this is a prominence fix, not new policy. SKILL.md was already exactly
at the 500-word cap, so the replacement bullet is net **-4 words**.
### Finding 2 — B18, enforcement layers not enumerated
- **Symptom:** An agent verified a Hetzner cloud firewall was open to
`::/0` for 80/443/ICMP, concluded the host was intended to be
dual-stack, and published AAAA records for a service whose traefik
`ipallowlist` allow-list carried IPv4 prefixes only. Office clients
preferring IPv6 would have reached traefik over v6 from an address
outside the allow-list and received a 403, with no fallback — Happy
Eyeballs retries connection failures, not HTTP errors. Caught by the
requester, then reverted.
- **Cause:** G1 covers adjacent components and G2 shared-layer
downstream. Neither covers *several enforcement layers stacked on one
request path*, so verifying the packet filter felt like sufficient
evidence.
- **Required behavior:** When a change alters how a service is reached,
enumerate every layer filtering by source address or identity and
confirm each covers the new path.
- **Change:** New `G4` row plus a matching entry under "Common false
negatives this catches".
## Verification
No `evals/` or `checkpoints.yaml` in this repo, so no automated gate was
added. Both changes are prose guidance in the QA checklist.
## Test plan
- [x] SKILL.md under the 500-word cap — `wc -w` incl. frontmatter, as
the gate counts it: **496** (main: 500)
- [x] `skill-repo/scripts/validate-skill.sh .` — 0 errors
- [ ] Stage -1 wording in SKILL.md does not contradict `lifecycle.md`
§Stage -1 or `edge-cases.md` §E
- [ ] `G4` does not duplicate `G1`/`G2`/`G3` scope2 files changed
Lines changed: 4 additions & 3 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
28 | 28 | | |
29 | 29 | | |
30 | 30 | | |
31 | | - | |
32 | | - | |
33 | | - | |
| 31 | + | |
| 32 | + | |
34 | 33 | | |
35 | 34 | | |
36 | 35 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
62 | 62 | | |
63 | 63 | | |
64 | 64 | | |
| 65 | + | |
65 | 66 | | |
66 | 67 | | |
67 | 68 | | |
| |||
71 | 72 | | |
72 | 73 | | |
73 | 74 | | |
| 75 | + | |
74 | 76 | | |
75 | 77 | | |
76 | 78 | | |
| |||
0 commit comments