From c148e518c319509b26aa785131749ce69fb0c0e6 Mon Sep 17 00:00:00 2001 From: JSONbored <49853598+JSONbored@users.noreply.github.com> Date: Sat, 25 Jul 2026 08:30:44 -0700 Subject: [PATCH] docs(skills): require full-scope completeness bar in gardening-generated issues Contributors' AI-harness agents read only the issue text and default to the least-effort interpretation that could plausibly close a checklist. Add an explicit completeness bar to the contributor-pipeline-gardening skill: every Requirement must be concrete/testable, every Deliverables item ships together in one PR (no partial credit for a subset), and Expected Outcome must be a falsifiable end-state checkable from the PR diff alone. --- .../contributor-pipeline-gardening/SKILL.md | 9 ++++ .../reference.md | 44 ++++++++++++++++++- 2 files changed, 52 insertions(+), 1 deletion(-) diff --git a/.claude/skills/contributor-pipeline-gardening/SKILL.md b/.claude/skills/contributor-pipeline-gardening/SKILL.md index a151dc9994..b1880c6ff8 100644 --- a/.claude/skills/contributor-pipeline-gardening/SKILL.md +++ b/.claude/skills/contributor-pipeline-gardening/SKILL.md @@ -181,6 +181,13 @@ undelivered issue sit unflagged. 7. Quality over the number in what gets filed — don't pad with weak/duplicate/vague issues. This is not license to stop early: see point 1's "if under floor" note. +**Every new issue must clear the full-scope completeness bar in `reference.md`** (reinforced by the +maintainer, 2026-07-25): concrete/testable Requirements, a Deliverables checklist that explicitly ships +together in one PR (not partial credit for a subset), and a falsifiable Expected Outcome. Contributors' +AI-harness agents read only the issue text and default to the least-effort interpretation that could +plausibly close the checklist — an issue that leaves any of that ambiguous gets exactly that outcome. +This is required on every issue this pass files, not just the ones with an existing precedent to name. + ## Pass 3 — Strategic epic/milestone health (once-per-day cadence) Beyond Pass 1/2's issue-level hygiene, this skill also runs a lighter, once-per-day strategic pass @@ -216,6 +223,8 @@ tracker in the scheduling layer handles that gate — not part of this file). tracker is contributor-facing; vague vision issues aren't actionable by a contributor anyway. 6. Link every new issue as a native sub-issue of its parent epic via `addSubIssue` where a real parent exists; give it a real milestone, same discipline as Pass 2. +7. Same full-scope completeness bar as Pass 2 (see above and `reference.md`) — no exceptions for + epic-sourced issues. ## Daily digest diff --git a/.claude/skills/contributor-pipeline-gardening/reference.md b/.claude/skills/contributor-pipeline-gardening/reference.md index b30b2807bd..9f78e2dc60 100644 --- a/.claude/skills/contributor-pipeline-gardening/reference.md +++ b/.claude/skills/contributor-pipeline-gardening/reference.md @@ -113,6 +113,45 @@ shape/format should be mirrored, per `.claude/skills/metagraphed/reference.md`'s Before publishing any batch, reread each finished issue body end-to-end — not just the diff of what changed — to catch exactly this class of self-contradiction. +## Full-scope completeness is mandatory — no partial-credit issues (reinforced 2026-07-25) + +Maintainer's own words, 2026-07-25: "contributors will throw their AI tools at this for the least +path of resistance and submit the shittiest / lowest quality stuff possible to get it completed as +fast as possible unless we are extremely explicit on exactly what we expect... I expect the entire +issue done flawlessly start to finish, not broken up into smaller pieces and nothing skipped." + +This extends the "Reuse-existing-pattern is mandatory" rule above from *which shape to follow* to +*how much of it must ship*. Every generated issue must leave zero room for a contributor's AI-harness +agent to rationally conclude that implementing a subset of the Deliverables checklist, or the +laziest-possible interpretation of a Requirement, satisfies the issue. + +**How to apply when authoring a new issue:** + +- **Requirements must be concrete and testable, never open to interpretation.** Not "add filters to + X" — name every filter param, its type, its validation behavior, and cite the exact sibling + route/field whose parameter-handling to mirror (per the precedent-callout rule above). +- **Every item in the Deliverables checklist ships together, in one PR, or the issue is not done.** + Say this explicitly in the issue body (a fixed closing line, see the template below) — don't rely on + the checklist format alone to imply it. A PR that completes 2 of 4 checklist items and asks to land + is a partial delivery, not a done issue. +- **Expected Outcome must be a falsifiable end-state, not a vague direction.** Someone (or an + automated reviewer) must be able to check yes/no from the PR diff alone — "the field now supports a + `sort` and `order` param, matching ``'s validation" is falsifiable; "the field is + improved" is not. +- **Don't under-scope a coherent unit of work just to make the issue look more approachable** — an + issue whose own Requirements are incomplete, or whose Deliverables can be half-satisfied and still + plausibly read as "done," invites exactly the shortcut-taking this section exists to prevent. This is + separate from splitting a genuinely large epic into multiple *sequential, individually-complete* + issues (e.g. the `types-epic B batch N` family) — each batch issue is itself fully scoped and + independently completable end to end, and that decomposition is fine. What's not fine is a single + issue that itself ships incomplete or half-satisfiable. +- Before publishing, reread the finished issue body and ask: "if a contributor did the least possible + work that could arguably satisfy this text, would that match what the maintainer actually wants + shipped?" If there's daylight between those two, tighten the text until there isn't. + +Applies to every new issue from Pass 2 and Pass 3, and to any existing issue's body that Pass 1 +rewrites for clarity — this is a standing authoring bar, not a one-time pass. + ## Issue body template ```md @@ -129,9 +168,12 @@ changed — to catch exactly this class of self-contradiction. - [ ] - [ ] +All of the above ship together in one PR — a PR that completes only some of these items does not +satisfy this issue. + ## Expected Outcome - + ## Links & Resources