diff --git a/linear/docs/process/linear_issue_template_evidence_contract_v2.md b/linear/docs/process/linear_issue_template_evidence_contract_v2.md index 5363260..15d05a1 100644 --- a/linear/docs/process/linear_issue_template_evidence_contract_v2.md +++ b/linear/docs/process/linear_issue_template_evidence_contract_v2.md @@ -27,6 +27,7 @@ Every "Done" claim must include: - GitHub PR link(s) using `linear_link_reference_policy_v1.md` format. - Linear issue link(s) using canonical full-title format. - Project scope check: correct project, standalone issue, or explicit blocker if tooling cannot remove a wrong project. +- Issue Type decision: evidence-based selection or correction using `linear_issue_type_decision_guide_v1.md`. - Status class check: implementation, docs/design/audit, or future/unstarted. - Label check: finalized labels applied only to finalized items; future items do not receive completion labels. - Bidirectional linking check: PR comment plus Linear issue comment/link verified, with no duplicate link-spam. @@ -96,6 +97,7 @@ PR-to-Linear closeout check: - PR: [BitPod-App/repo-name PR #123 — PR Title](https://github.com/BitPod-App/repo-name/pull/123) - Linear: [BIT-000 — Full Issue Title](https://linear.app/bitpod-app/issue/BIT-000/issue-slug) - Project scope: correct / standalone / blocked by tooling limitation +- Issue Type decision: Feature / Bug / Chore / Design / Plan / Release / left ambiguous; evidence source noted - Status class: implementation / docs-design-audit / future-unstarted - Labels: domain label + qa/pm result labels verified where finalized - Bidirectional links: PR comment verified; Linear attachment/comment verified; no duplicate retroactive comments diff --git a/linear/docs/process/linear_issue_type_decision_guide_v1.md b/linear/docs/process/linear_issue_type_decision_guide_v1.md new file mode 100644 index 0000000..01f4354 --- /dev/null +++ b/linear/docs/process/linear_issue_type_decision_guide_v1.md @@ -0,0 +1,160 @@ +# Linear Issue Type Decision Guide v1 + +Status: Active canonical BitPod guide +Owner: Product Development +Last updated: 2026-04-28 +Applies to: Product Development `Issue Type` selection, correction, and hygiene audits +Related canon: `linear_operating_model_v1.md`, `linear_operating_guide_v3.md`, `linear_issue_template_evidence_contract_v2.md` + +## Purpose + +Use this guide to choose, correct, and audit exactly one Linear `Issue Type` in a repeatable, evidence-based way. + +This guide is deliberately narrow. It does not redesign the taxonomy. It explains how to use the existing types: `Plan`, `Feature`, `Bug`, `Chore`, `Design`, and `Release`. + +This is the current active BitPod Linear process rubric. It may later be extracted into Taylor01/Hermes skills, but until that extraction exists this file is the canonical workspace guide. + +## Core rule + +Classify by the substance of the work, not by title wording. + +- Do **not** infer type from the issue title alone. +- Treat the title as a weak hint only. +- Body, scope, acceptance criteria, comments, linked PRs, merged code, and review evidence matter more. +- If the title conflicts with implementation or acceptance evidence, evidence wins. +- If evidence is too thin, flag ambiguity instead of pretending certainty. + +## Evidence hierarchy + +Use the strongest available evidence in this order: + +1. GitHub PR diff, merged code, commit history, and attached artifacts. +2. PR title/body, review context, and explicit issue links. +3. Linear description, scope, acceptance criteria, comments, and parent/child context. +4. Issue title, only as a weak hint. +5. Best judgment, only when evidence is incomplete but still sufficient to explain the decision. + +If a correction depends mostly on item 4 or weak item 5, leave a comment noting the ambiguity rather than silently normalizing. + +## Operational definitions + +| Type | Use when | Do not use when | +|---|---|---| +| `Bug` | The primary work fixes broken behavior, a regression, or a defect against expected behavior. | The work adds a capability that never existed, even if the title says "fix". | +| `Feature` | The primary outcome is a non-trivial new or enhanced user-facing or team-facing capability. | The work is only cleanup, docs, audit, dependency work, or prep with no shipped capability. | +| `Chore` | Maintenance, cleanup, dependency upgrades, refactors, docs-only work, audits, process/tooling upkeep, or enabling/prep work without new functionality. | The same PR also shipped a real capability; split Chore and Feature tickets when practical. | +| `Design` | The primary purpose is actual GUI, graphic design, visual branding, UI/UX, design-system, or implementation of linked design assets, usually Figma. | The work is code architecture, backend architecture, system design, technical design, planning, or docs that merely use the word "design". | +| `Plan` | The ticket is a parent rollout / epic-like container for a larger coherent effort, and the actionable work is completed through child issues. The parent is non-actionable except through child completion. | The ticket is itself the actionable implementation task. | +| `Release` | The ticket is a coordinated shipping object with a real release date, rollout scope, release checklist, version bump, or multi-feature ship gate. | The ticket is just a feature, PR, deployment task, or merged implementation with no release coordination object. | + +### Narrow `Design` test + +Use `Design` only if the answer is yes: + +> Does this include actual GUI or graphic design, and is the primary goal to improve UI/UX or visual branding by implementing or producing the linked design asset? + +If no, do not use `Design`. + +### Narrow `Release` test + +Use `Release` rarely. A true `Release` should usually include a real release date or release window, coordinated rollout scope, and shipping checklist. + +A `Release` issue should not move through normal implementation closure just because constituent PRs merged. Treat it as a release gate: acceptance and closure require release-readiness evidence, not only code evidence. + +For now, a true `Release` should block normal `Delivered` -> `Accepted` or `Done` progression until the release gate, PM decision, and shipping evidence are explicit. + +## Decision tree + +1. Is the ticket only a parent container whose child issues are the real tasks? + - Yes -> `Plan`. +2. Is it a coordinated ship/release object with real rollout scope, date/window, checklist, or version bump? + - Yes -> `Release`. +3. Is the primary work actual GUI/graphic/visual branding/UI-UX work, usually against linked design assets? + - Yes -> `Design`. +4. Is the primary work fixing broken or regressed expected behavior? + - Yes -> `Bug`. +5. Did the work ship a meaningful new or enhanced capability for users or the team? + - Yes -> `Feature`. +6. Is the work maintenance, cleanup, docs, audit, refactor, dependency, process, or enabling/prep work without new capability? + - Yes -> `Chore`. +7. If the answer is mixed: + - Split into separate typed tickets when practical, even when they share the same PR. + - If retroactive splitting is not practical, classify by the dominant shipped outcome and leave a comment explaining the evidence. +8. If evidence is weak: + - Do not force a type. Keep/set `needs-type` or leave a normalization comment with the missing evidence. + +## Retroactive correction rules + +Use these during hygiene audits, PR closeout, and after-the-fact ticket normalization. + +- If the PR clearly shipped a capability, classify by what actually shipped. +- If the work was docs/spec/audit/cleanup/refactor/dependency/process/enabling-only work, use `Chore`. +- The closeout status class `docs/design/audit` does not automatically mean Issue Type `Design`; most docs/audit/process work is `Chore`. +- If the work fixed broken behavior, use `Bug` even when the title says "feature". +- If the work implemented linked UI/UX or visual design assets, use `Design`; otherwise technical "design" is not `Design`. +- If one PR includes both enabling work and shipped capability, prefer separate `Chore` and `Feature` tickets linked to the same PR. +- If a parent ticket is only an umbrella whose completion comes from child tickets, use `Plan` even if the title sounds like a feature. +- If the body says one thing but the diff/artifacts show another, evidence wins. +- If there is no GitHub link, use the Linear body/comments and parent context; if those are thin, flag ambiguity. +- For historical `Done` / `Accepted` tickets with no estimate, do not invent points unless the sizing is obvious from the evidence and the cleanup pass explicitly authorizes backfill. +- Ambiguous historical cases can remain unresolved. A truthful ambiguity comment is better than a fake-clean audit. + +## Hygiene audit checklist + +For each issue in a hygiene audit: + +1. Confirm there is exactly one canonical `Issue Type`. +2. Review the strongest evidence available, especially linked PRs and merged code. +3. Apply the decision tree. +4. Correct only when the evidence supports the correction. +5. If correction is ambiguous, leave `needs-type` or a comment explaining the evidence gap. +6. Do not change estimate, priority, owner, or milestone just to make the audit look complete. +7. Add one concise normalization comment if the correction is non-obvious. + +Minimum audit mapping column: + +| Issue | Current type | Evidence reviewed | Decision | Confidence / ambiguity | +|---|---|---|---|---| + +## Normalization comment template + +```md +Issue Type normalization: +- Evidence reviewed: +- Decision: +- Rationale: +- Follow-up: +``` + +## Recent hygiene examples + +These examples are lightweight precedents, not permanent overrides. Re-check evidence when re-auditing. + +| Case | Decision pattern | Why | +|---|---|---| +| BIT-212 from the BIT-270 cleanup family | `Chore` | Supporting/cleanup work was normalized as maintenance rather than a shipped capability. | +| BIT-282 from the BIT-270 cleanup family | `Chore` | Retroactive metadata cleanup added missing type/estimate for supporting work. | +| BIT-283, BIT-303, BIT-304 from the BIT-270 cleanup family | `Feature` | The cleanup record says code/runtime reality had already shipped capability. | +| BIT-270-style parent rollout tickets | Check for `Plan` before preserving `Feature` | If the parent is only an umbrella and children are the executable work, the guide points to `Plan`. | +| BIT-35-style live admin/config lanes | Usually `Chore` | Workflow/admin/config/process upkeep is enabling work, not a product feature or `Design`. | + +## Open questions / edge cases + +Leave these explicit instead of silently resolving them: + +- Retroactive PR-backed tickets with thin body text: use best judgment only when PR evidence is strong enough to explain; otherwise leave ambiguous. +- `Done` / `Accepted` tickets with no estimate: backfill only when sizing is obvious and authorized for that cleanup pass; otherwise flag rather than guess. +- Multiple PRs on one issue: classify by dominant outcome only when clear; otherwise split tickets or leave an edge-case comment. +- No GitHub link: classify from Linear evidence only if sufficient; otherwise mark missing evidence. +- Title/body conflicts: implementation and acceptance evidence win. +- Scaffold/enabling work that shipped real capability: `Feature` if the primary accepted outcome is usable capability; `Chore` if it is only prep. +- Ambiguous historical cases: leave unresolved when correction would be mostly title inference or speculation. + +## Automation note + +Future hygiene automation should use this guide as the rubric, not as a title keyword matcher. + +- `Issue Type` validation may enforce exactly one canonical type. +- Type suggestion/correction must cite evidence source(s). +- Low-confidence suggestions should produce `needs-type` or an ambiguity comment, not an automatic correction. +- The PR-to-Linear mapping table should include an `Issue Type decision` column for normalization runs. diff --git a/linear/docs/process/linear_operating_guide_changelog.md b/linear/docs/process/linear_operating_guide_changelog.md index 295a2a9..e03c9b5 100644 --- a/linear/docs/process/linear_operating_guide_changelog.md +++ b/linear/docs/process/linear_operating_guide_changelog.md @@ -35,9 +35,11 @@ Maintenance update — 2026-04-28: - require a mapping table covering PRs, Linear issues, project scope, status class, labels, and bidirectional links - require single clean retroactive-link comments instead of duplicate or shorthand-only comments - make project-scope cleanup fail closed when available tooling cannot remove a wrong project assignment +- add the Issue Type decision guide as the evidence-based rubric for future hygiene audits and normal triage Linked artifacts: - `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/linear_operating_guide_v3.md` +- `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/linear_issue_type_decision_guide_v1.md` - `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/linear_admin_change_control_v1.md` - `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/linear_change_proposal_template_v1.md` - `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/linear_process_v1_1_control_tower_change_proposal_2026-04-15.md` diff --git a/linear/docs/process/linear_operating_guide_v3.md b/linear/docs/process/linear_operating_guide_v3.md index 3fece86..303fce5 100644 --- a/linear/docs/process/linear_operating_guide_v3.md +++ b/linear/docs/process/linear_operating_guide_v3.md @@ -26,6 +26,7 @@ Maintenance update — 2026-04-28: - require a small mapping table before merge, retroactive cleanup, or broad Linear normalization - make bidirectional GitHub PR and Linear issue links part of completion evidence - make project-scope classification explicit, especially for shared infrastructure that does not belong in product/model projects +- add `linear_issue_type_decision_guide_v1.md` as the evidence-based rubric for Issue Type triage and hygiene corrections ## Scope @@ -121,6 +122,7 @@ Maintenance update — 2026-04-28: 11. Weekly hygiene beats backlog drift - Keep Linear small and legible. - Close stale tickets, merge duplicates, and normalize missing acceptance criteria before adding more structure. +- Normalize missing or suspicious `Issue Type` values through `linear_issue_type_decision_guide_v1.md`; title-only type corrections are not allowed. - Prefer fewer labels unless a new label clearly solves repeated friction. 12. QA and PM truth must be honest @@ -137,7 +139,7 @@ Maintenance update — 2026-04-28: - Otherwise, the engine must leave a correction comment and stop short of closure. 14. PR-to-Linear closeout guardrail -- Before merge, retroactive linking, or Linear normalization, create a small mapping table with: GitHub PR, Linear issue(s), owning project, status class, required labels, and expected bidirectional links. +- Before merge, retroactive linking, or Linear normalization, create a small mapping table with: GitHub PR, Linear issue(s), owning project, status class, Issue Type decision, required labels, and expected bidirectional links. - Status class must be explicit: - PR-backed implementation: `Done` only after merge/evidence is real. - Docs/design/audit: `Accepted` when reviewed/accepted but not an implementation closure. @@ -190,6 +192,7 @@ This version corresponds to: - evidence-first completion protocol from `v2` - Taylor01 portability review gate from `taylor01_portability_review_gate_v1.md` - active issue evidence contract from `linear_issue_template_evidence_contract_v2.md` +- Issue Type decision rubric from `linear_issue_type_decision_guide_v1.md` - PR-to-Linear closeout guardrail added to `linear_operating_guide_v3.md` on 2026-04-28 - Linear admin/process change-control from `linear_admin_change_control_v1.md` - proposal workflow from `linear_change_proposal_template_v1.md` @@ -199,6 +202,7 @@ Artifacts: - `linear_operating_model_v1.md` - `linear_operating_guide_v3.md` - `linear_issue_template_evidence_contract_v2.md` +- `linear_issue_type_decision_guide_v1.md` - `taylor01_portability_review_gate_v1.md` - `linear_admin_change_control_v1.md` - `linear_change_proposal_template_v1.md` diff --git a/linear/docs/process/linear_operating_model_v1.md b/linear/docs/process/linear_operating_model_v1.md index cd3166a..0d686b6 100644 --- a/linear/docs/process/linear_operating_model_v1.md +++ b/linear/docs/process/linear_operating_model_v1.md @@ -212,6 +212,8 @@ This board is the closest Linear equivalent to a single meaningful Pivotal board ## Ticket types +Operational type selection, retroactive correction, and hygiene-audit normalization are governed by `linear_issue_type_decision_guide_v1.md`. This model defines the taxonomy; the decision guide defines how to apply it from evidence. + Canonical issue types: - `Plan` @@ -238,6 +240,7 @@ Canonical issue types: - no extra type taxonomy - `Plan` and `Release` are the only issue types where sub-issues are generally expected - outside of `Plan` and some `Release` tickets, sub-issues should usually be avoided +- issue type corrections must be evidence-based; do not infer type from title alone ### Feature definition