From 2542813c626bb2b3ab9752c9a339076f86da8f9b Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 1 Jun 2026 02:44:07 -0700 Subject: [PATCH] docs: tighten Method issue template evidence --- .github/ISSUE_TEMPLATE/bug.yml | 40 ++++++++++++++++++++++--- .github/ISSUE_TEMPLATE/spike.yml | 36 ++++++++++++++++++++-- .github/ISSUE_TEMPLATE/work-item.yml | 32 ++++++++++++-------- docs/invariants/sponsor-abstractness.md | 7 +++-- 4 files changed, 94 insertions(+), 21 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index a9d7477..99ac5cf 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -34,6 +34,18 @@ body: attributes: label: Impact description: Who is blocked or misled by this? + - type: textarea + id: sponsored-perspectives + attributes: + label: Sponsored perspectives + description: Name abstract sponsored human and agent seats, not literal people or model brands. + value: | + - Sponsored Human: Name the blocked operator, maintainer, contributor, or user perspective. + - Sponsored Agent: Name the automation, reproduction, review, or regression-detection perspective. + + These are Method sponsorship seats, not literal people, accounts, or model brands. + validations: + required: true - type: textarea id: acceptance attributes: @@ -46,8 +58,28 @@ body: id: witness attributes: label: Witness plan + description: Expected evidence for tests, playback, docs, and retro. + value: | + ### Tests + Name the failing regression test, reproduction command, or reason no code test applies. + + ### Playback + Name the human-visible reproduction, demo, transcript, or before/after proof. + + ### Docs + Name the documentation, issue template, signpost, or changelog surface updated, or explain why none is required. + + ### Retro / Closeout + Name the closeout note, follow-up issue links, shipped retro, or close reason that will preserve the decision. + validations: + required: true + - type: textarea + id: method-artifacts + attributes: + label: Method artifacts + description: Fill these links as the work proceeds. value: | - Expected evidence: - - failing test or reproduction: - - fix validation: - - retro: + - Design: Link `docs/design/--.md`, or state why issue-only triage is sufficient. + - Witness: Link committed witness evidence or the issue/PR comment that records verification. + - Retro: Link the retro/closeout artifact or the issue close comment. + - PR: Link the pull request before closing implementation work. diff --git a/.github/ISSUE_TEMPLATE/spike.yml b/.github/ISSUE_TEMPLATE/spike.yml index 58039fc..394feef 100644 --- a/.github/ISSUE_TEMPLATE/spike.yml +++ b/.github/ISSUE_TEMPLATE/spike.yml @@ -19,6 +19,18 @@ body: description: What decision will this unblock? validations: required: true + - type: textarea + id: sponsored-perspectives + attributes: + label: Sponsored perspectives + description: Name abstract sponsored human and agent seats, not literal people or model brands. + value: | + - Sponsored Human: Name the decision-maker, maintainer, contributor, or user perspective served by the learning. + - Sponsored Agent: Name the automation, analysis, implementation, or reproducibility perspective. + + These are Method sponsorship seats, not literal people, accounts, or model brands. + validations: + required: true - type: textarea id: constraints attributes: @@ -31,10 +43,30 @@ body: attributes: label: Expected evidence description: What transcript, demo, test, or artifact proves the learning? - placeholder: | - - [ ] ... + value: | + ### Tests + Name the probe command, fixture, regression test, or reason no code test applies. + + ### Playback + Name the transcript, demo, comparison, or decision evidence that proves the learning. + + ### Docs + Name the documentation, issue template, signpost, or changelog surface updated, or explain why none is required. + + ### Retro / Closeout + Name the adopt/adapt/retire decision, follow-up issue links, or close reason. validations: required: true + - type: textarea + id: method-artifacts + attributes: + label: Method artifacts + description: Fill these links as the work proceeds. + value: | + - Design: Link `docs/design/--.md`, or state why issue-only triage is sufficient. + - Witness: Link committed witness evidence or the issue/PR comment that records verification. + - Retro: Link the retro/closeout artifact or the issue close comment. + - PR: Link the pull request before closing implementation work. - type: textarea id: closeout attributes: diff --git a/.github/ISSUE_TEMPLATE/work-item.yml b/.github/ISSUE_TEMPLATE/work-item.yml index ab4bff9..57a505e 100644 --- a/.github/ISSUE_TEMPLATE/work-item.yml +++ b/.github/ISSUE_TEMPLATE/work-item.yml @@ -31,10 +31,12 @@ body: id: sponsored-perspectives attributes: label: Sponsored perspectives - description: Name abstract human and agent seats, not literal people or model brands. + description: Name abstract sponsored human and agent seats, not literal people or model brands. value: | - Human: - Agent: + - Sponsored Human: Name the served operator, maintainer, contributor, or user perspective. + - Sponsored Agent: Name the automation, implementation, review, or reproducibility perspective. + + These are Method sponsorship seats, not literal people, accounts, or model brands. validations: required: true - type: textarea @@ -75,11 +77,17 @@ body: label: Witness plan description: Expected evidence for tests, playback, docs, and retro. value: | - Expected evidence: - - tests: - - playback: - - docs: - - retro: + ### Tests + Name the deterministic test command, failing-before-fix reproduction, or reason no code test applies. + + ### Playback + Name the human-visible playback, demo, transcript, or reproduction that proves the result. + + ### Docs + Name the documentation, issue template, signpost, or changelog surface updated, or explain why none is required. + + ### Retro / Closeout + Name the closeout note, follow-up issue links, shipped retro, or close reason that will preserve the decision. validations: required: true - type: textarea @@ -88,7 +96,7 @@ body: label: Method artifacts description: Fill these links as the work proceeds. value: | - Design: - Witness: - Retro: - PR: + - Design: Link `docs/design/--.md`, or state why issue-only triage is sufficient. + - Witness: Link committed witness evidence or the issue/PR comment that records verification. + - Retro: Link the retro/closeout artifact or the issue close comment. + - PR: Link the pull request before closing implementation work. diff --git a/docs/invariants/sponsor-abstractness.md b/docs/invariants/sponsor-abstractness.md index eba3f8a..bb27f29 100644 --- a/docs/invariants/sponsor-abstractness.md +++ b/docs/invariants/sponsor-abstractness.md @@ -4,8 +4,8 @@ title: "Invariant: Role and Perspective Abstractness" ## What must remain true? -When METHOD says `Human`, `Agent`, or `User`, it means an abstract role -or perspective, not a specific individual, account, model brand, or +When METHOD says `Sponsored Human`, `Sponsored Agent`, `Human`, `Agent`, +or `User`, it means an abstract role or perspective, not a specific individual, account, model brand, or running agent instance. ## Why does it matter? @@ -23,7 +23,8 @@ present during authorship, review, or playback. ## How do you check? -- Design documents name sponsors as roles (e.g., "Human: System Architect"). +- Design documents and issue cards name sponsors as roles (e.g., + "Sponsored Human: System Architect"). - Doctrine uses `human`, `agent`, and `user` to describe seats or perspectives in the workflow, not literal identities. - No literal personal names or specific agent brand names are used in