diff --git a/src/docs/Ways-of-Working/Issues/Types/Bug.md b/src/docs/Ways-of-Working/Issues/Types/Bug.md new file mode 100644 index 0000000..bdbed03 --- /dev/null +++ b/src/docs/Ways-of-Working/Issues/Types/Bug.md @@ -0,0 +1,51 @@ +--- +title: Bug +description: One implementation-ready correction for unexpected behavior, delivered at Task level. +--- + +# Bug + +A Bug is a native delivery type at the same altitude as a [Task](Task.md). It owns one independently correctable instance of unexpected behavior and one reviewable pull request. + +Use Bug for a correction, not as a label or hierarchy level. A defect that needs multiple pull requests becomes a [PBI](PBI.md) with Bug and Task children. + +## Issue body + +Follow the universal [Issue Format](../Process/Format.md), with these Bug-specific contents. + +### Context and request + +- **Observed behavior:** what happens, including exact errors, outputs, or impact. +- **Expected behavior:** the observable result that should occur instead. +- **Reproduction:** the smallest repeatable steps, inputs, and commands. +- **Environment:** relevant versions, runtime, operating system, host, and configuration. +- **Regression:** whether this worked before and the last known working version, or an explicit unknown. +- **Workaround:** the current mitigation, or an explicit statement that none is known. +- **Acceptance criteria:** the corrected behavior and the regressions that must remain prevented. + +### Technical decisions + +- Bound the root cause to the affected behavior, component, contract, or change based on available evidence. +- Distinguish verified cause from hypotheses; do not use the correction to absorb unrelated refactoring. +- Record compatibility, failure-handling, and rollout decisions needed for the fix. +- Define the failing regression test that will demonstrate the problem before implementation. + +### Implementation plan + +Start by reproducing the failure in an automated regression test. Then implement the smallest root-cause correction, run the affected and broader test surfaces, and update relevant documentation. If automation is genuinely impossible, record the reason and an equivalent repeatable verification before implementation. + +## Ready + +A Bug is implementation-ready when: + +- observed and expected behavior, reproduction, environment, regression status, workaround, and acceptance criteria are explicit; +- the correction is bounded to one pull request; +- the root-cause boundary and unresolved hypotheses are clear enough to prevent scope drift; +- dependencies and blockers are known; and +- the regression-test-first plan can be executed. + +## Closure + +Close a Bug only after its pull request is reviewed and merged, the regression test or recorded equivalent fails before the correction and passes after it, and the acceptance criteria are verified. Record any intentionally deferred cleanup as linked Task children of the relevant PBI or as separate follow-up Tasks. + +See the [Issue Hierarchy](Hierarchy.md) for routing and promotion when investigation reveals more than one deliverable. diff --git a/src/docs/Ways-of-Working/Issues/Types/Epic.md b/src/docs/Ways-of-Working/Issues/Types/Epic.md new file mode 100644 index 0000000..7ba7377 --- /dev/null +++ b/src/docs/Ways-of-Working/Issues/Types/Epic.md @@ -0,0 +1,58 @@ +--- +title: Epic +description: A strategic repository aggregate that turns one Initiative into measurable outcomes and PBIs. +--- + +# Epic + +An Epic is the native issue type for a strategic outcome that needs multiple PBIs in one repository. It is an aggregate: progress comes from its native sub-issues, not from an implementation branch or closing pull request. + +Use an Epic when the work connects strategy to several bounded bodies of work. Use a [PBI](PBI.md) when one bounded outcome is enough. + +## Strategy boundary + +An Initiative is an organization-level bet under an OKR; an Epic is that Initiative's repository-level delivery aggregate. Link the Initiative and relevant OKR rather than copying their full bodies. When an Initiative spans repositories, each repository owns the Epic for its part of the outcome. + +The Epic states the repository contribution through the Golden Circle: + +- **Why:** the problem, strategic objective, and Key Result this work is expected to move. +- **How:** the capability-level approach and boundaries, without implementation detail. +- **What:** the observable repository outcomes the child PBIs collectively deliver. + +## Issue body + +Follow the universal [Issue Format](../Process/Format.md), with these Epic-specific contents. + +### Context and request + +- Link the parent Initiative and relevant OKR. +- State the strategic outcome through Why, How, and What. +- Define success measures with a baseline or current state, a target, and how the result will be observed. +- Bound the in-scope and out-of-scope outcomes. +- Write aggregate acceptance criteria that prove the PBIs combine into the intended outcome. + +### Technical decisions + +- Record the chosen scope boundaries and significant trade-offs. +- Explain the decomposition into PBIs and why each boundary is independently meaningful. +- Identify interfaces, ownership boundaries, dependencies, and sequencing between PBIs. +- Keep implementation decisions in the child PBI, Task, or Bug where they can be made at the right altitude. + +### Implementation plan + +Use native sub-issues for the child PBIs. The plan may summarize those links and their intended outcomes, but it does not contain an inline implementation checklist. + +## Ready + +An Epic is ready for decomposition when: + +- the Initiative and OKR relationship is linked and the repository boundary is clear; +- Why, How, What, success measures, scope, and aggregate acceptance criteria are explicit; +- the initial PBI boundaries, interfaces, dependencies, and ownership are understood; and +- no open decision prevents the first PBIs from becoming ready. + +## Aggregate closure + +Close an Epic only when every required child PBI is complete, the aggregate acceptance criteria are verified, and the success measures have current evidence. Move any intentionally deferred outcome to a linked follow-up before closure. Record the final evidence in the Epic; do not close it through a direct implementation pull request. + +See the [Goal-Setting Framework](../../Goal-Setting.md) for the Mission, OKR, and Initiative model and the [Issue Hierarchy](Hierarchy.md) for containment and routing. diff --git a/src/docs/Ways-of-Working/Issues/Types/Hierarchy.md b/src/docs/Ways-of-Working/Issues/Types/Hierarchy.md index dc7263d..f9c6dff 100644 --- a/src/docs/Ways-of-Working/Issues/Types/Hierarchy.md +++ b/src/docs/Ways-of-Working/Issues/Types/Hierarchy.md @@ -1,125 +1,66 @@ --- title: Issue Hierarchy -description: Delivery (Task or Bug), PBI, and Epic — the three operational levels. +description: Shared taxonomy, routing, containment, and promotion rules for native issue types. --- # Issue Hierarchy -Work in the MSX ecosystem is tracked using GitHub sub-issues to form a connected hierarchy from Epic down to individual deliverables. The level reflects **scope and aggregation**, not priority or complexity. We use **GitHub issue types** for the segmentation — not labels — so the relationships are first-class in the platform. +The MSX issue hierarchy separates strategic aggregation from delivery. Altitude reflects outcome scope and containment, not priority, effort, uncertainty, or organizational structure. -Epics originate from Initiatives in the [Goal-Setting Framework](../../Goal-Setting.md). +## Taxonomy -## Full hierarchy +| Altitude | Native issue type | Owns | Delivery | +| --- | --- | --- | --- | +| Strategic aggregate | [Epic](Epic.md) | One repository outcome tied to an Initiative and delivered by multiple PBIs. | Progress and closure aggregate from child PBIs. | +| Bounded aggregate | [PBI](PBI.md) | One bounded outcome delivered by multiple child issues. | Progress and closure aggregate from Tasks, Bugs, or nested PBI children. | +| Delivery leaf | [Task](Task.md) | One planned deliverable. | One pull request, or one audited and independently verified operational action. | +| Delivery leaf | [Bug](Bug.md) | One correction for unexpected behavior. | One pull request with regression-first verification. | -```text -Epic (initiative from an OKR, repo-level) -├── PBI (body of work, multiple PRs) -│ ├── Task (one PR-sized deliverable) -│ └── Bug (one PR-sized correction) -└── PBI - └── Task -``` - -GitHub supports up to **8 levels** of nested sub-issues and **100 sub-issues per parent**, which comfortably fits this model with room to spare. - -## The three operational levels - -| Level | Issue type | Scope | Output | -| ------------------------ | ------------- | ---------------------------------------------------- | ---------------------------------------------------------- | -| **Delivery** | `Task`, `Bug` | One deliverable. One small reviewable PR. | Working software. | -| **Product Backlog Item** | `PBI` | A body of work composed of multiple delivery issues. | Tracking, delegation, oversight, visibility into progress. | -| **Epic** | `Epic` | Strategic chunk needing multiple PBIs. | The co-planning artifact. Where OKRs become initiatives. | - -> The name **Product Backlog Item** is chosen for its neutral vibe — it works equally well for a feature, a fix, a refactor, or an internal capability. "Feature" implies user-visible value, which isn't always the case for the middle tier. - -Epic and PBI are aggregation types. Task and Bug are delivery leaves: use Task for planned work and Bug for an unexpected problem or behavior, with both sized to one reviewable pull request. Feature remains enabled temporarily while existing Feature issues are migrated; it is not a level in the target operational hierarchy and is retired only after that migration is complete. - -## When to use each level - -### Task or Bug - -Use Task or Bug when: - -- The work has one clear deliverable. -- The expected PR is small and reviewable in a single pass (rough guideline: under ~500 lines / 15 files). -- One person (or one agent) can pick it up and finish it independently. - -A Task is the **default starting point** for planned work; use Bug when the deliverable corrects unexpected behavior. Promote upward only when you discover the work is too big. - -### Product Backlog Item - -Use PBI when: +Bug is a native delivery type at Task altitude, not a label or an additional hierarchy level. -- The work has multiple distinct deliverables, each of which would be its own PR. -- The deliverables share a goal but can be sequenced or parallelized. -- You want oversight over the body of work without prescribing the order. +Feature remains temporary live metadata while [migration task #90](https://github.com/MSXOrg/docs/issues/90) retires existing usage. It describes a kind of work, not planning altitude, and must not be used as a hierarchy node. -A PBI's children can themselves be PBIs (nested decomposition) when the inner deliverables also break into multiple chunks. Epic → PBI → PBI → Task is legitimate when the work demands it. +## Routing -### Epic +Start at a delivery leaf and promote only when the work proves larger: -Use Epic when: +- Use **Task** for one planned repository deliverable or one audited operational action. +- Use **Bug** for one independently correctable instance of unexpected behavior. +- Use **PBI** when one bounded outcome needs multiple pull requests or independently completable actions. +- Use **Epic** when one repository's strategic outcome implements an Initiative through multiple PBIs. -- The work spans multiple PBIs. -- It maps to a strategic objective — an OKR, an initiative, an organizational goal. -- Multiple teams or contributors should co-plan around it. +A defect that requires multiple pull requests is a PBI with Bug children for independently correctable behavior and Task children for planned enabling, migration, or follow-up work. Do not stretch one Bug across several pull requests. -> "As a business we want to deliver this. What do we collectively need to do?" - -That conversation lives on an Epic. - -## Nested decomposition +## How to express the hierarchy -Nesting is fine and expected: +Use GitHub's native sub-issue relationship for containment: ```text -Epic (initiative, ties to an OKR) -├── PBI (one body of work) -│ ├── Task (one PR) -│ ├── Task -│ └── PBI (further breakdown when needed) -│ ├── Task -│ └── Task +Epic └── PBI - └── Task + ├── Task + ├── Bug + └── PBI + └── Task or Bug ``` -The rule: **one Task or Bug = one PR-sized deliverable**. Everything above is for aggregation. - -## How to express the hierarchy - -Use GitHub's native **sub-issue relationship** for containment between aggregation issues and their children. Containment does not imply sequence. When one issue must finish before another can proceed, use the native **blocked-by / blocking relationship** to express that execution order. The Planner agent creates both kinds of relationship during decomposition. - -Text-level conventions on child issues are courtesy duplicates of the native relationships: - -- `Parent: #N` at the top of Section 1 (a courtesy duplicate of the GitHub link). -- `Blocked by: #M` when sequencing matters (a courtesy duplicate of the native dependency). -- Acceptance criteria scoped to **just this child's slice**, not the parent's whole goal. +- Epic and PBI are aggregates. Their children own delivery branches, pull requests, or operational evidence. +- Task and Bug are leaves and do not aggregate implementation work through sub-issues. +- A nested PBI is valid only when its bounded child outcome still needs multiple delivery issues. +- Each child's acceptance criteria cover only its slice; the parent owns criteria for the combined outcome. +- Containment does not imply sequence. Use native blocked-by and blocking relationships when execution order matters. -## How the sections differ by level - -| Section | Task | PBI | Epic | -| ------------------------ | ----------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | -| Section 1 (Context/Req) | The deliverable's user story | The grouped goal's user story | The strategic outcome — vision, why, the change in the world | -| Section 2 (Decisions) | Implementation decisions | Decomposition rationale + interface decisions between children | Decomposition rationale + which PBIs and why | -| Section 3 (Plan) | Checkbox task list | Linked list of child issues (Tasks and/or sub-PBIs) | Linked list of child PBIs | - -For Epics, Section 1 should explicitly contain the **Golden Circle framing**: Why, How, What. See [Principles → Golden Circle](../../Principles/Purpose-and-Direction.md#start-with-why-the-golden-circle). - -## Why three levels and not more - -Three is enough to: - -- Cover **strategic** (Epic), **tactical** (PBI), and **operational** (Task) horizons. -- Match how teams co-plan in larger frameworks (SAFe, Nexus) without inheriting their ceremony. -- Aggregate progress meaningfully — an Epic burns down as its PBIs complete; a PBI burns down as its Tasks complete. - -More levels create overhead. Fewer levels lose the ability to track progress across bodies of work. +GitHub's native relationships are the source of truth. Text links may aid readers, but they do not replace the platform relationship. ## Promotion and demotion -A Task can be **promoted** to a PBI when it turns out to be bigger than expected. The Planner does this — Section 2 records the discovery, and the inline task list becomes child issues. +Change type when decomposition reveals the issue is at the wrong altitude: + +- Promote a Task or Bug to PBI when it needs multiple delivery children. +- Promote a PBI to Epic only when it represents a strategic repository outcome tied to an Initiative and needs multiple PBIs. +- Demote a PBI to Task or Bug when only one delivery leaf remains. +- Demote an Epic to PBI when it represents one bounded outcome rather than a strategic aggregate. -A PBI can be **demoted** to a Task when decomposition reveals only one real deliverable. Close the would-be-children, fold their content into the Task's Section 3. +Update the issue body for its new type, rebuild native containment, and add an audit comment explaining what changed and why. Promotion or demotion preserves the original issue whenever practical so its discussion and decisions remain traceable. -Promotion / demotion always leaves a comment audit trail explaining the change. +See the [Goal-Setting Framework](../../Goal-Setting.md) for the Initiative boundary and the [Issue Format](../Process/Format.md) for the universal body structure. diff --git a/src/docs/Ways-of-Working/Issues/Types/PBI.md b/src/docs/Ways-of-Working/Issues/Types/PBI.md new file mode 100644 index 0000000..1672184 --- /dev/null +++ b/src/docs/Ways-of-Working/Issues/Types/PBI.md @@ -0,0 +1,53 @@ +--- +title: PBI +description: A bounded outcome delivered through multiple Tasks, Bugs, or nested PBI sub-issues. +--- + +# PBI + +A Product Backlog Item (PBI) is the native issue type for one bounded outcome that needs multiple deliverables. It is an aggregate: child issues own implementation, while the PBI owns their combined result. + +Use a PBI when the outcome needs more than one pull request or independently completable operational action. Use a [Task](Task.md) or [Bug](Bug.md) when one deliverable is enough. + +## Issue body + +Follow the universal [Issue Format](../Process/Format.md), with these PBI-specific contents. + +### Context and request + +- State one bounded user, operator, or maintainer outcome. +- Define in-scope and out-of-scope boundaries. +- Write aggregate acceptance criteria that verify the children work together, not criteria copied from each child. +- Identify constraints and dependencies that affect the whole body of work. + +### Technical decisions + +- Explain the decomposition into Tasks, Bugs, or nested PBIs. +- Define interfaces, contracts, ownership boundaries, and integration points between children. +- Record cross-child sequencing with native blocked-by relationships; containment alone does not imply order. +- Keep child-local implementation decisions in the child issue. + +### Implementation plan + +Use native sub-issues for every delivery child. The plan may summarize the linked children and their outcomes, but it does not replace them with an inline implementation checklist. + +## Nested PBIs + +Nest a PBI only when one child outcome is itself bounded but still needs multiple independent deliverables. Do not add nesting to mirror teams, components, phases, or reporting structure. If a nested PBI has only one real deliverable, demote it to a Task or Bug. + +A defect that needs multiple pull requests is a PBI, not an oversized Bug. Decompose it into [Bug](Bug.md) children for independently correctable unexpected behavior and [Task](Task.md) children for planned enabling, migration, or follow-up work. + +## Ready + +A PBI is ready for delivery when: + +- the bounded outcome, scope, and aggregate acceptance criteria are testable; +- interfaces, dependencies, and integration expectations are explicit; +- the work is decomposed far enough that the first delivery children meet their own readiness gates; and +- no unresolved decision would materially change the child boundaries. + +## Aggregate closure + +Close a PBI only when every required child is complete and the aggregate acceptance criteria have been verified across their combined output. Move deferred work to linked follow-ups and record integration or operational evidence in the PBI. A PBI does not own a direct implementation branch or closing pull request. + +See the [Issue Hierarchy](Hierarchy.md) for containment, routing, and promotion or demotion. diff --git a/src/docs/Ways-of-Working/Issues/Types/Task.md b/src/docs/Ways-of-Working/Issues/Types/Task.md new file mode 100644 index 0000000..745edbc --- /dev/null +++ b/src/docs/Ways-of-Working/Issues/Types/Task.md @@ -0,0 +1,62 @@ +--- +title: Task +description: One implementation-ready planned deliverable completed by one pull request or one audited operation. +--- + +# Task + +A Task is the native issue type for one planned delivery leaf. It owns one independently verifiable deliverable and does not aggregate implementation sub-issues. + +Repository work follows one Task, one branch, and one reviewable pull request. Work that has several independently deliverable pull requests is a [PBI](PBI.md). + +## Issue body + +Follow the universal [Issue Format](../Process/Format.md), with these Task-specific contents. + +### Context and request + +- State the single user, operator, or maintainer outcome. +- Write observable, testable acceptance criteria for that deliverable. +- Identify constraints, dependencies, and explicit non-goals. +- Link the parent PBI or Epic when the Task is part of an aggregate. + +### Technical decisions + +- Resolve the implementation choices needed to start without rediscovery. +- Name the repository paths, components, interfaces, and existing patterns involved. +- Record compatibility, failure-handling, migration, documentation, and test decisions when applicable. +- Leave no open decision that could materially change the implementation plan. + +### Implementation plan + +Write an actionable checkbox plan at repository-path and behavior level. For each behavior, put the test or verification step before its implementation step, following the [test-first standard](../../../Coding-Standards/Testing.md#test-first). Include documentation and final validation in the same plan. + +The checklist describes one pull request. If it reveals independent deliverables, promote the issue to a PBI and create delivery children. + +## Ready + +A Task is implementation-ready when: + +- it contains one deliverable with testable acceptance criteria; +- required technical decisions, paths, interfaces, dependencies, and blockers are resolved; +- the test-first implementation plan is specific enough to execute without replanning; and +- the expected output fits one reviewable pull request or the audited operational path below. + +## Completion paths + +### Repository delivery + +Create one branch and draft pull request for the Task. The pull request implements the checklist, verifies the acceptance criteria, and closes only this Task after review and merge. + +### Operational delivery + +Use this path only when the deliverable creates no repository artifact to review. The issue must name the action, expected evidence, and verifier before work starts. Completion requires an audit comment that records: + +- what was performed and by whom; +- when and where it was performed; +- links or captured output that provide durable evidence; and +- an independent verification result against every acceptance criterion. + +Close the Task only after that verification succeeds. A verbal confirmation or an unaudited action is not completion. + +See the [Contribution Workflow](../../Contribution-Workflow.md) for repository delivery and the [Issue Hierarchy](Hierarchy.md) for routing and promotion. diff --git a/src/docs/Ways-of-Working/Issues/Types/index.md b/src/docs/Ways-of-Working/Issues/Types/index.md index 630a17a..f56b94a 100644 --- a/src/docs/Ways-of-Working/Issues/Types/index.md +++ b/src/docs/Ways-of-Working/Issues/Types/index.md @@ -11,6 +11,10 @@ How native issue types organize delivery and aggregation. | Page | Description | | --- | --- | -| [Issue Hierarchy](Hierarchy.md) | Delivery (Task or Bug), PBI, and Epic — the three operational levels. | +| [Issue Hierarchy](Hierarchy.md) | Shared taxonomy, routing, containment, and promotion rules for native issue types. | +| [Epic](Epic.md) | A strategic repository aggregate that turns one Initiative into measurable outcomes and PBIs. | +| [PBI](PBI.md) | A bounded outcome delivered through multiple Tasks, Bugs, or nested PBI sub-issues. | +| [Task](Task.md) | One implementation-ready planned deliverable completed by one pull request or one audited operation. | +| [Bug](Bug.md) | One implementation-ready correction for unexpected behavior, delivered at Task level. | diff --git a/src/zensical.toml b/src/zensical.toml index f6b7b05..7e67a04 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -59,6 +59,10 @@ nav = [ {"Types" = [ "Ways-of-Working/Issues/Types/index.md", {"Hierarchy" = "Ways-of-Working/Issues/Types/Hierarchy.md"}, + {"Epic" = "Ways-of-Working/Issues/Types/Epic.md"}, + {"PBI" = "Ways-of-Working/Issues/Types/PBI.md"}, + {"Task" = "Ways-of-Working/Issues/Types/Task.md"}, + {"Bug" = "Ways-of-Working/Issues/Types/Bug.md"}, ]}, ]}, {"PR Format" = "Ways-of-Working/PR-Format.md"},