docs: document contribution evidence gate and label taxonomy - #4478
Open
mnriem wants to merge 4 commits into
Open
docs: document contribution evidence gate and label taxonomy#4478mnriem wants to merge 4 commits into
mnriem wants to merge 4 commits into
Conversation
Add an "Evidence gate" subsection, a high-level "Review rubric" (D1-D7, scored 0-2 each), and a "Triage and author labels" reference to CONTRIBUTING.md so the acceptance bar is discoverable before contributing. Cross-links the existing AI-contributions section and three-open-PR cap rather than restating them. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Copilot review overview
🟢 Approval recommended
The changes are documentation-only and appear consistent and well-structured, with only minor wording/typo nits noted inline.
Review tier: Lite
Findings: 1
New issues introduced by this change (1)
| Severity | Finding |
|---|---|
 |
CONTRIBUTING.md — The phrase "hands off to" is ungrammatical here and reads like a typo; it’s likely meant to… |
What changed in this PR
This PR documents Spec Kit’s “evidence gate” and related review/triage guidance directly in CONTRIBUTING.md, making contribution expectations discoverable to contributors before they submit changes.
Changes:
- Adds an “Evidence gate” subsection describing what qualifies as acceptable evidence for changes.
- Adds a concise D1–D7 “Review rubric” table used to guide prioritization.
- Documents
triage-*verdict labels andauthor-*action labels, plus a link to an explicitly non-policy perspective piece.
| File | Description |
|---|---|
| CONTRIBUTING.md | Adds new PR-submission subsections for evidence, rubric scoring, and triage/author label taxonomy. |
Suppressed comments (1)
CONTRIBUTING.md:112
- "AI-source contributions" reads like a typo/awkward phrasing; "AI-sourced contributions" is the common grammatical form for contributions originating from AI output.
For further reading on the thinking behind this gate, see [one maintainer's perspective on AI-source contributions](https://blog.manorrock.com/blog/2026/09/08/spec_kit_ai_source.html). That piece is a personal viewpoint, not project policy — the policy is what's documented here.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
mnriem
added
the
triage-must-have
Add author-needs-proof and author-needs-rebase to the author-actions table,
a "Community catalog submissions" subsection pointing catalog changes at the
submission-issue flow, and a note on when items are closed as
triage-out-of-scope. Fix the author-awaiting phrasing ("handed off to").
author-needs-rescope is intentionally omitted: it does not yet exist on
github/spec-kit, so it is flagged for the maintainer rather than documented
as a live label.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Copilot review overview
🟢 Approval recommended
The change is documentation-only and appears internally consistent, with only a minor wording nit identified.
Review tier: Lite
Findings: 1
New issues introduced by this change (1)
| Severity | Finding |
|---|---|
|
CONTRIBUTING.md — Link text uses "AI-source contributions", which reads like a typo/grammar error and is inconsistent… |
Issues resolved since last review (1)
| Severity | Finding |
|---|---|
|
CONTRIBUTING.md — The phrase "hands off to" is ungrammatical here and reads like a typo; it’s likely meant to… View resolved comment |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
The documented author-* label taxonomy currently doesn’t match the repo’s actual labels/descriptions (including a non-existent label), so the guidance would be misleading.
Review tier: Lite
Findings: None
Issues resolved since last review (1)
| Severity | Finding |
|---|---|
|
CONTRIBUTING.md — Link text uses "AI-source contributions", which reads like a typo/grammar error and is inconsistent… View resolved comment |
Suppressed comments (1)
Previously missed (1) — in code that hasn't changed since the last review.
CONTRIBUTING.md:113
- The “Author actions” label table doesn’t match the repository’s actual labels:
author-needs-rescopedoesn’t exist, and several descriptions differ from the current label descriptions (e.g.,author-needs-proof,author-needs-rebase,author-awaiting). To keep this section self-documenting and avoid drift, align the table to the exact label set/descriptions (or drop labels that aren’t present).
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
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.
What & why
Spec Kit's acceptance bar — an "evidence gate" applied identically to human and AI-assisted contributions — currently lives in maintainers' heads. This PR moves it into
CONTRIBUTING.mdso the bar is discoverable before someone contributes. Docs/policy only; no CLI, tests, templates, or extensions are touched.Changes
Three new
###subsections under## Submitting a pull request(after the three-open-PR-cap paragraph, before### Branch naming):triage-can-waitand held behind proven work. Spells out what counts as evidence (reproduction/linked report, a regression test that fails onmainand passes with the change, scope discipline, disclosed AI use).0–2(14 max). Framed as guiding prioritization, not a hard pass/fail gate.triage-*verdict andauthor-*action labels, using the exact names/descriptions already on the repo.Existing content (the AI-contributions section and the three-open-PR cap) is cross-linked, not restated or contradicted. A companion perspective piece is linked as further reading and explicitly marked as a personal viewpoint, not policy.
Validation
markdownlint-cli2 CONTRIBUTING.md— no new violations introduced (the two pre-existing MD048 findings on the reporting-template blocks are unrelated to this change).gh label list --repo github/spec-kit.AI disclosure
This PR was authored by GitHub Copilot (model: Claude Opus 4.8) operating autonomously on behalf of @mnriem.