docs(delivery),chore(skills): plain-language rule and triage fixes from the first live triage - #140
Merged
Merged
Conversation
…om the first live triage (#79) Rule 12: everything an agent writes on an issue or PR is short and plain, with word budgets. Rule 8: the title is the claim the test proves, the root cause says defect or gap, side findings become bug:new issues. triage-bug: title narrowed to what the test observes, assert the whole claim, read-only host inspection allowed and disclosed, defect/gap/decision triage, side-findings step, report budget. deliver and spec-session point at rule 12 for handoffs, PR bodies, and spec text.
…rect, worktree rule, report caps Rule 12: agent text confirms or corrects the body instead of restating it, and every comment, issue body, and PR body ends with '*Written by an agent.*'. Rule 13: assume every agent is in a worktree; branch from origin/*, never switch to a branch another checkout may hold. Rule 8: alternatives at most three one-liners, risk at most three bullets. The needs-info job ignores comments carrying the footer, so an agent's own comment on a bug the maintainer reported cannot flip the label.
…eeds-info job ignores agent comments; worktree-safe branching in deliver
…fore posting, bug:ready on a gap accepts the proposed shape
…e agent footer with contains
V3RON
added a commit
that referenced
this pull request
Sep 10, 2026
…, request close, claim release (#142) ## Summary Closes the state-machine holes found after two live triage runs. Verification stays part of delivery: no verify state, no verify skill. **Blocked has a state.** `bug:blocked`, `feature:blocked`, `task:blocked`. An agent sets it when its handoff names a blocker; the maintainer clears it by re-adding the label it came from. Without this a blocked handoff left the issue `*:ready`, so the next agent claimed it and hit the same wall. Sending it to `task:draft` would not have worked either, because the approval box is still ticked and the automation promotes it straight back. **Verification is part of delivery.** Rule 9, DELIVERY.md, and `deliver` now say: every task PR walks its Done when, and the PR that closes the last open sub-issue also walks the parent's Completion conditions. The completion note on the feature tells the maintainer to close it. **`issue-state.yml`**, three new jobs and three amended: | Job | Change | |---|---| | `task-ready` | also demotes `task:ready` → `task:draft` when the approval, the spec, or a closed dependency goes away; runs on `reopened` too; a claimed task is left alone | | `needs-info-reply` | reopens the issue if the stale job had closed it, so the stale comment's promise is true | | `feature-complete` | renamed from `feature-verify`; the note says "close it once the completion conditions hold" | | `request-close` (new) | a feature closed as completed closes the `request:new` issue on its `Request:` line, with a pointer | | `pr-closed-unmerged` (new) | a PR closed without merging releases the claim on every issue its body closes, with a comment; label untouched | | `stale-claims` (new) | daily: a `*:ready` issue with an assignee and no comment, label change, or commit on `<kind>/<n>` for three days is unassigned, with a comment | **Manifest.** Restores `bug:triaged`, which #140 lost to a reformat (the live label exists), and adds the three blocked labels. ## Not done, on purpose Review-feedback state, an unlabelled-issue nudge, and `feature:specified` were left out as low value for now.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes from the first live triage (#79), and a writing rule for everything agents post.
Rule 12, new. Everything an agent writes on an issue or PR is short and plain: conclusion first, short sentences, common words, evidence in code blocks, nothing that does not change the reader's next decision. Word budgets: triage report 300, handoff 150, PR body 200 plus checklist, "Spec updated" comment one line.
Rule 8, amended. The test title is the claim the test proves, not the claim the bug makes. Root cause says defect or gap first. Side findings become
bug:newissues listed in a sixth section.triage-bug. What the #79 run showed the skill was missing:bug:newissuedeliver,spec-session. Point at rule 12 for handoffs, PR bodies, and spec text.Added after review of the first run:
*Written by an agent.*, since agents post under a maintainer's account.origin/*, never switch to a branch another checkout may hold.deliverandtriage-bugcarry the commands, including the temporary-name push when the local name is taken.issue-state.yml: the needs-info job ignores comments ending with the agent footer, so an agent's comment on a bug the maintainer reported cannot flipbug:needs-infotobug:triage.deliver: before the PR, searchdocs/and user-facing strings for claims the change makes false and fix them in the same PR.bug:readyaccepts the shape the report proposes; to reject the shape but keep the reproduction, reply and re-addbug:triage.bug:triaged, new label: a posted report moves the bug out ofbug:triageso no triage agent picks it up again and the maintainer sees it is waiting on them. Back tobug:triageby re-adding the label. Created live and applied to iOS on-demand runtime downloads never actually free disk space (mobileassetd cache outlives simctl runtime delete) #79.triage-bug: a replacement report starts with "Supersedes the report above."issue-state.yml: droppedtrim(), which is not an Actions expression function and made the file invalid; the footer is matched withcontainsand tolerates_or*.