📖 [Docs]: Operational issue taxonomy and relationships clarified (#83)

The issue hierarchy guidance now reflects the live MSXOrg operational
taxonomy and distinguishes work aggregation from delivery and
sequencing.

## Changed: Issue hierarchy roles and relationships

Epic and PBI aggregate work, while Task and Bug represent one
pull-request-sized delivery. Feature remains temporarily enabled pending
migration. Native sub-issues represent containment, and blocked-by /
blocking dependencies represent execution order.

## Technical Details

- `Issue-Hierarchy.md` records the five-type transition state and the
target Epic/PBI/Task/Bug operating model.
- The linked issue’s audit comments record the separate organization API
configuration and relationship-surface verification; those live platform
changes are not part of this repository diff.
- Implementation plan progress: this pull request completes the
documentation task in #82.

<details>
<summary>Related issues</summary>

- Fixes #82

</details>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

src/docs/Ways-of-Working/Issue-Format.md

@@ -45,9 +45,9 @@ The description has three sections separated by horizontal rules (`---`), ordere
 
 | Section                   | Owner                 | Present in                                                    |
 | ------------------------- | --------------------- | ------------------------------------------------------------- |
-| 1 — Context and Request   | Ideator → Clarifier   | Every issue at every level (Task, PBI, Epic)                  |
-| 2 — Technical Decisions   | Planner               | Task always; PBI / Epic for decomposition rationale           |
-| 3 — Implementation Plan   | Planner               | Task always (task list); PBI / Epic (links to children)       |
+| 1 — Context and Request   | Ideator → Clarifier   | Every issue at every level (Task, Bug, PBI, Epic)              |
+| 2 — Technical Decisions   | Planner               | Task / Bug always; PBI / Epic for decomposition rationale     |
+| 3 — Implementation Plan   | Planner               | Task / Bug always (task list); PBI / Epic (links to children) |
 
 ## Section 1 — Context and Request
 
@@ -408,4 +408,4 @@ Labels categorize. The category is never encoded in the title.
 | `Feature`   | Feature requests                                     |
 | `Question`  | Questions or discussion                              |
 
-Issue **types** (Epic / PBI / Task) are GitHub-native and separate from labels — see [Issue Hierarchy](Issue-Hierarchy.md).
+Issue **types** are GitHub-native and separate from labels. The operational types are Epic / PBI / Task / Bug; see [Issue Hierarchy](Issue-Hierarchy.md) for their roles and Feature's temporary retention.

src/docs/Ways-of-Working/Issue-Hierarchy.md

@@ -1,6 +1,6 @@
 ---
 title: Issue Hierarchy
-description: Epic, PBI, and Task — the three operational levels.
+description: Delivery (Task or Bug), PBI, and Epic — the three operational levels.
 ---
 
 # Issue Hierarchy
@@ -15,7 +15,7 @@ Epics originate from Initiatives in the [Goal-Setting Framework](Goal-Setting.md
 Epic (initiative from an OKR, repo-level)
 ├── PBI (body of work, multiple PRs)
 │   ├── Task (one PR-sized deliverable)
-│   └── Task
+│   └── Bug (one PR-sized correction)
 └── PBI
     └── Task
 ```
@@ -24,25 +24,27 @@ GitHub supports up to **8 levels** of nested sub-issues and **100 sub-issues per
 
 ## The three operational levels
 
-| Level                    | Issue type   | Scope                                              | Output                                                     |
-| ------------------------ | ------------ | -------------------------------------------------- | ---------------------------------------------------------- |
-| **Task**                 | `Task`       | One deliverable. One small reviewable PR.          | Working software.                                          |
-| **Product Backlog Item** | `PBI`        | A body of work composed of multiple Tasks.         | Tracking, delegation, oversight, visibility into progress. |
-| **Epic**                 | `Epic`       | Strategic chunk needing multiple PBIs.             | The co-planning artifact. Where OKRs become initiatives.   |
+| 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
+### Task or Bug
 
-Use Task when:
+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**. Promote upward only when you discover the work is too big.
+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
 
@@ -82,16 +84,16 @@ Epic (initiative, ties to an OKR)
     └── Task
 ```
 
-The rule: **one Task = one PR-sized deliverable**. Everything above is for aggregation.
+The rule: **one Task or Bug = one PR-sized deliverable**. Everything above is for aggregation.
 
 ## How to express the hierarchy
 
-Use GitHub's **sub-issue relationship** between issue types. This is a first-class GitHub feature — not just text references — and the Planner agent creates these relationships when decomposing.
+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:
+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.
+- `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.
 
 ## How the sections differ by level

src/docs/Ways-of-Working/index.md

@@ -31,7 +31,7 @@ This section documents the principles, processes, and norms that every contribut
 | [Goal-Setting Framework](Goal-Setting.md) | Mission, OKRs, and initiatives — strategy connected to delivery. |
 | [Definition of Ready and Done](Definition-of-Ready-and-Done.md) | The three gates that bracket every piece of work. |
 | [Issue Format](Issue-Format.md) | The three-section issue structure, formatting, and labels. |
-| [Issue Hierarchy](Issue-Hierarchy.md) | Epic, PBI, and Task — the three operational levels. |
+| [Issue Hierarchy](Issue-Hierarchy.md) | Delivery (Task or Bug), PBI, and Epic — the three operational levels. |
 | [PR Format](PR-Format.md) | Pull request title, description, change types, and labels. |
 | [Commit Conventions](Commit-Conventions.md) | How commit messages are written. |
 | [Branching and Merging](Branching-and-Merging.md) | Topic branches, pull-request-only integration, and merge models. |