📖 [Docs]: Operational issue taxonomy and relationships clarified

[Marius Storhaug (MariusStorhaug)]

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 Configure Epic and PBI issue types #82.

Related issues

• Fixes Configure Epic and PBI issue types #82

[Copilot]

Pull request overview

Updates the issue-hierarchy documentation to reflect MSXOrg’s live operational taxonomy, clearly separating aggregation issue types from delivery issue types and clarifying how to represent containment vs sequencing in GitHub.

Changes:

• Updates the hierarchy model so Task/Bug are the PR-sized delivery leaves, while Epic/PBI are aggregation layers (with Feature explicitly called out as temporary during migration).
• Refines the “when to use” guidance to cover Task vs Bug as the delivery-level choice.
• Clarifies relationship semantics: sub-issues for containment; blocked-by/blocking for execution order (with optional text-level courtesy duplicates).

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

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

• Terminology is inconsistent: this paragraph uses "blocked-by / blocking relationship" but the convention below uses "Blocked by:" (no hyphen). Align the wording with the actual label you want contributors to use (e.g., "blocked by / blocking").

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.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

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

• The taxonomy update introduces “Delivery (Task or Bug)” as the operational leaf level, but later in this page the “Why three levels and not more” section still describes the operational horizon as “Task” only. That makes the page internally inconsistent and can mislead readers/agents about whether Bug is part of the operational level. Please update that later wording to refer to Delivery (Task/Bug) instead of Task alone.

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.