The issue-first rule currently admits no exceptions: AGENTS.md §3 says "For every change: 1. Open a GitHub issue first", and CONTRIBUTING.md's workflow says the same.
In practice we now allow one. A change small enough to explain itself goes straight to a PR, labelled no-issue, with a final line NO-ISSUE: <short reason>. First used in deck-eval-gen#20.
Until that is written down, the documented rule and the practice disagree — so the next agent either files an issue for a one-line docs fix, or reads a no-issue PR as a violation of the canonical guide.
Three touch points, not one
The exception affects more than step 1. A no-issue PR also has no number for the branch name (step 2) and nothing to put in Closes #N (CONTRIBUTING step 5).
AGENTS.md §3 — add under step 1:
- Exception: a change small enough to explain itself — a typo, a doc clarification, recording a decision already made — may go straight to a PR. Label it
no-issue and end the description with NO-ISSUE: <short reason>. Use a real issue whenever the change needs discussion or has acceptance criteria.
and in step 2, after <issue-number>-<short-slug>: (or a descriptive slug, for a no-issue PR).
CONTRIBUTING.md — the same exception on step 1, the same branch-name parenthetical on step 2, and on step 5 note that a no-issue PR carries the NO-ISSUE: trailer in place of Closes #N. Add the rationale there, since CONTRIBUTING carries the why: the ceremony is real and worth paying when a change needs a decision recorded, and pure overhead when it doesn't — the label and trailer keep the exception visible and auditable rather than silent.
The label
Should no-issue join the canonical label set? It had to be created by hand in deck-eval-gen. Nothing in settings.yml or create-repo.sh manages labels today, so either every repo grows it ad hoc, or label management becomes a (small) new responsibility for the reconciler. Worth deciding here rather than discovering it per repo.
Acceptance criteria
- Both files describe the exception, including branch naming and the missing
Closes #N.
- A decision recorded on the label question.
Note this issue exists partly on principle: CONTRIBUTING.md says rules land "via a PR closing a tracking issue", so a change to the rules is exactly the case the exception should not cover.
The issue-first rule currently admits no exceptions: AGENTS.md §3 says "For every change: 1. Open a GitHub issue first", and CONTRIBUTING.md's workflow says the same.
In practice we now allow one. A change small enough to explain itself goes straight to a PR, labelled
no-issue, with a final lineNO-ISSUE: <short reason>. First used indeck-eval-gen#20.Until that is written down, the documented rule and the practice disagree — so the next agent either files an issue for a one-line docs fix, or reads a
no-issuePR as a violation of the canonical guide.Three touch points, not one
The exception affects more than step 1. A
no-issuePR also has no number for the branch name (step 2) and nothing to put inCloses #N(CONTRIBUTING step 5).AGENTS.md §3 — add under step 1:
and in step 2, after
<issue-number>-<short-slug>: (or a descriptive slug, for ano-issuePR).CONTRIBUTING.md — the same exception on step 1, the same branch-name parenthetical on step 2, and on step 5 note that a
no-issuePR carries theNO-ISSUE:trailer in place ofCloses #N. Add the rationale there, since CONTRIBUTING carries the why: the ceremony is real and worth paying when a change needs a decision recorded, and pure overhead when it doesn't — the label and trailer keep the exception visible and auditable rather than silent.The label
Should
no-issuejoin the canonical label set? It had to be created by hand indeck-eval-gen. Nothing insettings.ymlorcreate-repo.shmanages labels today, so either every repo grows it ad hoc, or label management becomes a (small) new responsibility for the reconciler. Worth deciding here rather than discovering it per repo.Acceptance criteria
Closes #N.Note this issue exists partly on principle: CONTRIBUTING.md says rules land "via a PR closing a tracking issue", so a change to the rules is exactly the case the exception should not cover.