From 5a72efa0029809fa38086191bb42c73b54890a0e Mon Sep 17 00:00:00 2001 From: "pulse-triage[bot]" <249995291+pulse-triage[bot]@users.noreply.github.com> Date: Sat, 29 Aug 2026 12:44:25 +0100 Subject: [PATCH] Ship the issue triage contract Change-source: pulse-maintainer --- .../public/docs/AI_TRANSPARENCY.md | 7 ++- frontend-modern/public/docs/CONTRIBUTING.md | 5 +- frontend-modern/public/docs/ISSUE_TRIAGE.md | 55 +++++++++++++++++++ 3 files changed, 64 insertions(+), 3 deletions(-) create mode 100644 frontend-modern/public/docs/ISSUE_TRIAGE.md diff --git a/frontend-modern/public/docs/AI_TRANSPARENCY.md b/frontend-modern/public/docs/AI_TRANSPARENCY.md index 019a7269f..832e96a71 100644 --- a/frontend-modern/public/docs/AI_TRANSPARENCY.md +++ b/frontend-modern/public/docs/AI_TRANSPARENCY.md @@ -29,8 +29,11 @@ released builds still go through Pulse's release qualification process. and the evidence used to qualify a release. - **Issue triage and support.** Automated issue and discussion replies post under the dedicated `pulse-triage` bot identity and link back to this page. - Automated issue state changes use that identity as well. Automated support - replies are sent as Pulse Triage and link here as well. + Automated issue state changes use that identity as well. Mixed reports follow + the [topic-integrity triage contract](ISSUE_TRIAGE.md): automation can surface + declared secondary topics, but a maintainer or triage agent must give every + actionable topic a linked disposition. Automated support replies are sent as + Pulse Triage and link here as well. - **Change provenance.** Commits made by the continuously running maintainer carry a dedicated bot author and committer identity. Issue-driven changes link back to the originating report where applicable. diff --git a/frontend-modern/public/docs/CONTRIBUTING.md b/frontend-modern/public/docs/CONTRIBUTING.md index 1e45031aa..6df41b817 100644 --- a/frontend-modern/public/docs/CONTRIBUTING.md +++ b/frontend-modern/public/docs/CONTRIBUTING.md @@ -41,7 +41,10 @@ and installer tooling. - State the Pulse version and image or package you are actually running. - Include screenshots, logs, API output, or diagnostics when they clarify the problem. -- Separate bug reports from feature requests; avoid mixing both into one issue. +- Lead with one primary bug or operator outcome. If the context also exposes + another actionable topic, put it in the issue form's dedicated field. Triage + will preserve it with a linked disposition; you do not need to refile text + you already supplied. See [Issue Triage and Topic Integrity](docs/ISSUE_TRIAGE.md). --- diff --git a/frontend-modern/public/docs/ISSUE_TRIAGE.md b/frontend-modern/public/docs/ISSUE_TRIAGE.md new file mode 100644 index 000000000..092361224 --- /dev/null +++ b/frontend-modern/public/docs/ISSUE_TRIAGE.md @@ -0,0 +1,55 @@ +# Issue Triage and Topic Integrity + +Pulse issue triage must preserve every actionable topic a reporter contributes. +Resolving the primary defect does not dispose of secondary bugs, feature requests, +documentation gaps, or operator workflows described in the same report. + +## Intake contract + +Issue forms ask for one primary outcome and provide an **Additional actionable +topics** field. Entering anything other than `None` applies the +`needs-decomposition` label automatically. This is a queue-integrity signal, +not a statement that every topic will be built. + +Reporters may still write free-form issues, edit form output, or discover a +second topic during discussion. Triage owns decomposition in those cases; it +must not require the reporter to refile information they already supplied. + +## Required disposition + +Before removing `needs-decomposition` or declaring a mixed report triaged: + +1. Enumerate each independently actionable topic in the issue body and comments. +2. Keep the original issue focused on its primary reproducible problem. +3. Give every other topic one linked disposition: + - a new or existing issue for a distinct defect or independently actionable + product request; + - a demand-ledger entry for evidence that is useful but not yet build-ready; + - a Discussion or support path when there is no reproducible defect or + product decision to track; + - an explicit decline, with the reason, when the topic conflicts with Pulse's + product or safety boundaries. +4. Use GitHub sub-issue relationships when separate issues share the same source + report and the authenticated mutation path supports them. A plain backlink + remains in each child body so the evidence survives clients that do not + render sub-issues and remains the fallback for bounded bot identities. +5. Post a concise topic-to-disposition summary on the source issue. Never say a + topic is “recorded” without naming where it is recoverable. + +Decomposition does not multiply demand. Every child points to the same reporter +and source thread, and the demand ledger counts that as one signal per capability. +Do not copy credentials, private diagnostics, or personal data into a child +issue; summarize only the minimum sanitized evidence needed to preserve the +operator problem. + +## Automation boundary + +The label synchronizer detects the structured form field deterministically and +fails quietly for legacy forms. It does not use keyword heuristics to invent +topics or create issues automatically. A maintainer or triage agent reviews the +source context, chooses the correct destination, creates links, and is +accountable for the disposition. + +This boundary is deliberate: preserving an explicit reporter declaration is +safe to automate, while deciding whether two observations are one root cause is +a product and technical judgment.