diff --git a/src/docs/Ways-of-Working/Issues/Process/Format.md b/src/docs/Ways-of-Working/Issues/Process/Format.md index 4b22e34..56ba0c2 100644 --- a/src/docs/Ways-of-Working/Issues/Process/Format.md +++ b/src/docs/Ways-of-Working/Issues/Process/Format.md @@ -1,411 +1,58 @@ --- title: Issue Format -description: The three-section issue structure, formatting, and labels. +description: Universal title, body, audit, and formatting rules for every issue. --- # Issue Format -Every issue in the MSX ecosystem follows the same structure. The format makes issues: - -- **Readable** by anyone — human or agent — without prior context. -- **Actionable** by an implementer without back-and-forth. -- **Traceable** because decisions and changes are recorded. - -## Properties of every issue - -- **Every change has an issue.** Features, fixes, refactors, documentation, maintenance — all tracked as issues before work begins. -- **The description is the single source of truth.** It reflects the current state of the work at all times. Decisions, scope changes, and approach changes are written directly into the description. -- **Comments record change history only.** Each description update is accompanied by a comment summarizing what changed and why. -- **Tone is impersonal.** No first-person ("I", "my") or second-person ("you", "your") language. Neutral references like "the user", "the developer", or passive constructions. -- **External references are hyperlinks.** Every mention of an API, RFC, library, doc, or tool is a clickable `[text](url)` link. No bare URLs. -- **No duplicates.** Existing issues are searched before creating or restructuring. Duplicates are consolidated or cross-linked. +Every issue in the MSX ecosystem follows the same universal rules. The issue's native type determines the body detail; use the guidance for [Epic](../Types/Epic.md), [PBI](../Types/PBI.md), [Task](../Types/Task.md), or [Bug](../Types/Bug.md) rather than adding type-specific conventions here. ## Title -A clear, imperative-mood statement of the work. Not a question, not a symptom. - -- Scope or area when it aids disambiguation: `release pipeline: Add retry logic to the publish step`. -- No type prefixes (`[Bug]`, `[Feature]`) — labels handle categorization. - -### Well-formed - -- `Add pagination support to the repository list command` -- `Fix null reference when the session context is not resolved` -- `Update installation guide with prerequisites` - -### Malformed - -- `Bug in module` -- `Please fix` -- `WIP` - -## The three sections - -The description has three sections separated by horizontal rules (`---`), ordered from behavioural to architectural to tactical. The user need is understood before the technical discussion. - -| Section | Owner | Present in | -| ------------------------- | --------------------- | ------------------------------------------------------------- | -| 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 - -Describes the **user experience** — what someone wants, what isn't working, or what is missing. Written from the user's perspective, not the implementer's. - -Two parts: - -- **Context** — who the user is, what they're trying to accomplish, the situation. -- **Request** — the problem or need, as the user experiences it. - -Answers: - -- What does the user want to do? -- What is the user experiencing today (for bugs / gaps)? -- What should the experience look like instead? -- Why does it matter? - -Framing by work type: - -| Type | Framing | -| -------------- | ------------------------------------------------------------------------------------ | -| Feature | **Desired capability:** The desired capability from the user's point of view. | -| Bug / Fix | **What happens:** / **What is expected:** Observed vs. expected behavior. | -| Change request | **Current experience:** / **Desired experience:** The shift from the user's lens. | -| Maintenance | **User impact:** How internal work improves reliability, speed, or correctness. | -| Documentation | **What is confusing or missing:** The gap from a user trying to accomplish a task. | - -Elements per work type: - -| Element | Feature | Bug / Fix | Change request | Maintenance | Documentation | -| ------------------------ | :-----: | :-------: | :------------: | :---------: | :-----------: | -| Acceptance criteria | ✓ | ✓ | ✓ | ✓ | ✓ | -| Reproduction steps | | ✓ | | | | -| Environment / version | | ✓ | | | | -| Regression indicator | | ✓ | | | | -| Known workarounds | | ✓ | ○ | | | -| Error messages / logs | | ✓ | | ○ | | -| Screenshots / visuals | ○ | ✓ | ○ | | ○ | - -✓ = present when applicable, ○ = optional - -Element definitions: - -- **Reproduction steps** — a [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example): exact steps, inputs, and commands that trigger the problem. Anyone can reproduce the failure without guessing. -- **Environment / version** — tool version, runtime version, and operating system. Other relevant runtime details (host application, execution context) included as applicable. Omitted only when clearly version-independent. -- **Regression indicator** — whether this previously worked, and in which version. If unknown, stated explicitly. -- **Known workarounds** — any mitigation available today, even if ugly or incomplete. - -This section contains: - -- Context: user story or scenario, background, what the user is trying to accomplish -- Request: the specific problem, gap, or desired change — as the user experiences it -- Current vs. desired experience -- Impact of not addressing this (data loss, confusion, blocked workflows) -- Acceptance criteria — what "done" looks like from the user's perspective -- Applicable work-type-specific elements from the table above -- Links to related issues, PRs, or external references — every external resource is a clickable hyperlink - -This section **does not contain** file paths, function internals, API endpoints, or implementation patterns. Those belong in Section 2. The section is understandable by someone who has never read the source code. - -**Example (Bug / Fix):** - -```markdown -The `repo list` command is used in automation to sync all repositories for an account. -The script relies on getting the full list so it can detect new or removed repositories. - -## Request +Write a clear, imperative statement of the outcome or work: -When `repo list` is run on an account with more than 30 repositories, only 30 results are returned. -There is no indication that results are incomplete, so it appears as though the full list has been retrieved. -The silent truncation causes scripts to miss repositories, which can go unnoticed for weeks. +- Name the scope when it aids disambiguation. +- Describe the requested result, not a question, symptom, or status. +- Do not add type prefixes such as `[Bug]` or `[Feature]`; the native issue type carries that meaning. -### Reproduction steps - -1. Create or use an account with more than 30 repositories -2. Run `repo list` -3. Count the returned objects — only 30 are returned regardless of total count - -### What is expected - -The command should return **all** repositories by default. If there is a way to limit results, -it should be opt-in — not the default. - -### Environment - -- **Tool version:** 0.14.0 -- **OS:** Ubuntu 22.04 (Linux) - -### Regression - -This appears to have been the behavior since the initial release. Not a regression. - -### Workaround - -Calling the REST API directly with manual pagination returns all results. - -### Acceptance criteria - -- All repositories are returned by default, regardless of how many exist -- Results can be limited with a parameter when only a subset is needed -- No silent data loss — if something limits results, it should be explicit -``` - -**Example (Feature):** - -```markdown -Automation scripts that publish releases to multiple registries currently call the `publish` command -in a loop for each target. There is no built-in way to publish to several registries in a single invocation. - -## Request - -### Desired capability - -A `--registry` option on the `publish` command that accepts a list of registry names, publishing -to each in sequence. If any single publish fails, the error should be reported per-registry -without aborting the remaining targets. - -### Acceptance criteria - -- `--registry` accepts one or more registry names -- Each target is attempted independently — a failure on one does not block the others -- Output clearly indicates success or failure per registry -``` - -## Section 2 — Technical Decisions - -The technical choices that shape the plan. Sits between the user-facing request and the tactical plan. - -Why this section exists: - -- Different technical choices lead to fundamentally different plans — deciding upfront avoids rework. -- Conscious, documented choices replace implicit assumptions buried in code. -- Reviewers see the **reasoning** behind the plan, not just the plan itself. - -Structure: - -- Each decision is a bolded label or heading, followed by the chosen approach and a brief rationale. -- Alternatives considered are included when they help explain the choice. -- Open decisions are marked with `Open:` and resolved before the implementation plan is written. -- When a decision changes later, this section is updated and a comment documents the change. - -Typical decision areas: - -- Where new code lives (paths, modules). -- Patterns or conventions followed (e.g., "follow the existing pattern in the release command"). -- Naming choices. -- Whether to extend or create new. -- Dependencies on other functions, modules, or APIs. -- Error handling strategy. -- Breaking changes and backward compatibility. -- Test strategy (unit, integration, mocks). - -**Example:** - -```markdown ---- +## Body -## Technical decisions +The body is the current source of truth. It: -**Code placement:** New helper goes in `src/lib/` following the existing -request-helper pattern. The public command stays in `src/commands/repository/`. +- Explains the issue's local purpose and desired outcome without requiring prior context. +- States observable acceptance criteria. +- Records the decisions and plan needed at the issue's [planning altitude](Planning.md). +- Links to durable specifications, designs, prior decisions, pull requests, or external references instead of duplicating them. +- Changes as understanding, readiness, and scope change through the [issue lifecycle](Lifecycle.md). -**Pagination approach:** Use link-header-based pagination (`rel="next"`) rather than page-number incrementing. -The REST API uses link headers consistently, and this avoids hardcoding page size assumptions. +Keep information at its owning altitude. User-visible intent precedes technical detail, and implementation choices do not leak into outcome-level acceptance criteria. The type pages define which sections and evidence are required at each altitude. -**Parameter naming:** Use `--limit` (consistent with common CLI convention) rather than -`--max` or `--max-results`. +## Native metadata and relationships -**Breaking changes:** None. Default behavior changes from returning one page to returning all pages, but since the -previous behavior was undocumented and returning incomplete data, this is treated as a bugfix rather than a breaking change. +Assign the native issue type and maintain [native relationships](Relationships.md) in GitHub. Labels may classify release impact or repository-specific concerns, but they do not replace issue types, containment, dependencies, or readiness. -**Test approach:** Unit tests with mocked API responses. One test per scenario: single-page, multi-page, and `--limit` limiting. -``` +Do not duplicate metadata or relationships in the body. In particular, do not add manual `Parent:` or `Blocked by:` fields, copied child-link lists, or prose that treats list position as execution order. -## Section 3 — Implementation Plan +## Audit trail -The task-level roadmap. Implementers track progress here; reviewers use it to understand scope. +Edit the body whenever the current truth changes, then add a comment that briefly records: -Structure: +- What changed. +- Why it changed. +- Any unresolved question or follow-up. -- Every discrete piece of work is a checkbox: `- [ ]`. -- Tasks are grouped under subheadings when work spans multiple behaviors or dependencies. Keep each behavior's tests with its implementation tasks. -- Each task is specific and actionable — file paths, function names, modules. -- All tasks start unchecked. Checking happens during implementation. -- Order groups and tasks so scope and dependencies are clear; the checklist layout is not a mandatory execution sequence. -- Follow [test-first development](../../../Coding-Standards/Testing.md#test-first): define and run a behavior's test before implementing that behavior, regardless of how its checkboxes are organized. - -For PBIs and Epics, Section 3 is **a list of links to child issues**, not inline tasks. See [Issue Hierarchy](../Types/Hierarchy.md). - -**Example:** - -```markdown ---- - -## Implementation plan - -### Paged responses - -- [ ] Add unit test for single-page response -- [ ] Add unit test for multi-page response -- [ ] Add a paged-request helper in `src/lib/` -- [ ] Update the `repo list` command to call the paged variant in `src/commands/repository/` - -### Result limiting - -- [ ] Add unit test for `--limit` option limiting results -- [ ] Add a `--limit` option with integer type and validation - -### Documentation - -- [ ] Update command help with new option documentation -- [ ] Add example showing pagination usage -``` - -## Comments - -Every description update is accompanied by a comment. Comments preserve the change history so reasoning is not lost when the description is overwritten. - -A comment contains: - -- A brief summary line. -- Bullet points detailing what was added, changed, or removed. -- Any gaps or open questions that need input. - -**Example:** - -```markdown -Structured the issue description into the standard three-section format. - -- Rewrote the context and request to separate user-facing behavior from technical details -- Added technical decisions section based on codebase research -- Created implementation plan with 6 tasks covering core changes, tests, and documentation -- Open question: should `-First` default to unlimited or require explicit opt-in? Marked as open in technical decisions. -``` +Comments preserve the audit trail; they do not become a second current specification or plan. ## Formatting -Issues use [GitHub Flavored Markdown](https://github.github.com/gfm/) with the full feature set: +Use [GitHub Flavored Markdown](https://github.github.com/gfm/) to make the body easy to scan: -- `- [ ]` / `- [x]` task lists. -- Tables for comparisons, label definitions, decision matrices. +- Headings for distinct concerns. +- Task lists only where the type guidance calls for tracked work. +- Tables only when comparison is clearer than prose. - Fenced code blocks with language identifiers. -- `>` blockquotes for callouts. -- `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]` alerts. -- `
` collapsible sections. -- `#123`, `@user`, and commit SHA autolinks. -- Backtick-wrapped inline code for identifiers. -- `---` horizontal rules between sections. -- `[text](url)` links for all external references. -- **No hard line breaks within a paragraph.** GitHub renders mid-paragraph newlines as spaces, which creates inconsistent visual spacing. - -## Complete example - -A fully structured bugfix issue: - -**Title:** `Fix silent truncation of results in the repo list command` - -**Labels:** `Patch`, `Bug` - -**Body:** - -```markdown -The `repo list` command is used in automation to sync all repositories for an account. -The script relies on getting the full list so it can detect new or removed repositories. - -## Request - -When `repo list` is run on an account with more than 30 repositories, only -30 results are returned. There is no indication that results are incomplete, so it appears -as though the full list has been retrieved. The silent truncation causes scripts to miss -repositories, which can go unnoticed for weeks. - -### Reproduction steps - -1. Create or use an account with more than 30 repositories -2. Run `repo list` -3. Count the returned objects — only 30 are returned regardless of total count - -### What is expected - -The command should return **all** repositories by default. If there is a way to limit -results, it should be opt-in — not the default. - -### Environment - -- **Tool version:** 0.14.0 -- **OS:** Ubuntu 22.04 (Linux) - -### Regression - -This appears to have been the behavior since the initial release. Not a regression. - -### Workaround - -Calling the REST API directly with manual pagination returns all results. - -### Acceptance criteria - -- All repositories are returned by default, regardless of how many exist -- Results can be limited with a parameter when only a subset is needed -- No silent data loss — if something limits results, it should be explicit - ---- - -## Technical decisions - -**Code placement:** New helper goes in `src/lib/` following -the existing request-helper pattern. The public command stays in -`src/commands/repository/`. - -**Pagination approach:** Use link-header-based pagination (`rel="next"`) rather than page-number -incrementing. The REST API uses link headers consistently, and this avoids hardcoding page -size assumptions. - -**Parameter naming:** Use `--limit` (consistent with common CLI convention) -rather than `--max` or `--max-results`. - -**Breaking changes:** None. Default behavior changes from returning one page to returning all pages, -but since the previous behavior was undocumented and returning incomplete data, this is treated as a -bug fix rather than a breaking change. - -**Test approach:** Unit tests with mocked API responses. One test per scenario: single-page, -multi-page, and `--limit` limiting. - ---- - -## Implementation plan - -### Paged responses - -- [ ] Add unit test for single-page response -- [ ] Add unit test for multi-page response -- [ ] Add a paged-request helper in `src/lib/` -- [ ] Update the `repo list` command to call the paged variant in `src/commands/repository/` - -### Result limiting - -- [ ] Add unit test for `--limit` option limiting results -- [ ] Add a `--limit` option with integer type and validation - -### Documentation - -- [ ] Update command help with new option documentation -- [ ] Add example showing pagination usage -``` - -## Labels - -Labels categorize. The category is never encoded in the title. - -| Label | Use for | -| ----------- | ---------------------------------------------------- | -| `Major` | Breaking changes | -| `Minor` | New features or enhancements | -| `Patch` | Small fixes or improvements | -| `NoRelease` | Documentation, maintenance, CI/CD — no version bump | -| `Bug` | Bug reports | -| `Feature` | Feature requests | -| `Question` | Questions or discussion | +- Backticks for identifiers and commands. +- Markdown links for external references rather than bare URLs. +- Horizontal rules when they clarify the transition between intent, decisions, and plan. -Issue **types** are GitHub-native and separate from labels. The operational types are Epic / PBI / Task / Bug; see [Issue Hierarchy](../Types/Hierarchy.md) for their roles and Feature's temporary retention. +Write each paragraph as a single unbroken line. Prefer concise body content and link to the canonical source instead of restating it. diff --git a/src/docs/Ways-of-Working/Issues/Process/Lifecycle.md b/src/docs/Ways-of-Working/Issues/Process/Lifecycle.md new file mode 100644 index 0000000..476a501 --- /dev/null +++ b/src/docs/Ways-of-Working/Issues/Process/Lifecycle.md @@ -0,0 +1,20 @@ +--- +title: Issue Lifecycle +description: How issue bodies, types, readiness, and relationships evolve through the workflow. +--- + +# Issue Lifecycle + +[Workflow](../../Workflow.md) is the sole definition of the Capture, Refine, Plan, Build, Review, Ship, and Operate phases. This page maps only how an issue's body, native type, readiness, and relationships evolve while work passes through those phases. + +| Workflow phase | Issue evolution | +| --- | --- | +| **Capture** | Create the issue with the known need, affected user or operator, and desired outcome. Assign the best provisional native type. The item is not ready merely because it exists; add native relationships only when they are already known. | +| **Refine** | Correct the body until the problem, local purpose, scope, and observable acceptance criteria are clear. Correct the type when the planning altitude becomes known. Discover containment and dependencies and record them as [native relationships](Relationships.md). | +| **Plan** | Add the decisions and decomposition appropriate to the type's [planning altitude](Planning.md). Promote, demote, or split the issue when its scope requires a different type. Establish sub-issues and dependency edges, then mark the item ready only when it meets the [Definition of Ready](../../Definition-of-Ready-and-Done.md#definition-of-ready). | +| **Build** | Pull a ready Task or Bug whose blockers are clear. Keep its body and checklist current as implementation changes the plan. Parent progress comes from native sub-issue completion, while blocked-by edges continue to gate execution. | +| **Review** | Verify the delivered change against the issue's current acceptance criteria and decisions. Keep the pull request draft until it meets the separate [Definition of Ready for Review](../../Definition-of-Ready-and-Done.md#definition-of-ready-for-review). Record plan or scope corrections in the issue body and audit them in comments. | +| **Ship** | Merge the reviewed delivery pull request and close its Task or Bug through the pull request's closing link. Native completion updates parent progress. Close a PBI or Epic only when its native children and aggregate acceptance criteria are complete. | +| **Operate** | Feed production signals and learning back into the issue model. Reopen the issue when its accepted outcome is no longer true, or capture a new issue and relate it natively when the signal describes distinct work. | + +Readiness is a gate, not a phase label. A captured or refined issue remains unready until its intent, acceptance criteria, scope, dependencies, and open questions satisfy the shared readiness contract. Relationship and type changes follow the same [audit-trail rule](Format.md#audit-trail) as body changes. diff --git a/src/docs/Ways-of-Working/Issues/Process/Planning.md b/src/docs/Ways-of-Working/Issues/Process/Planning.md new file mode 100644 index 0000000..23d9b0b --- /dev/null +++ b/src/docs/Ways-of-Working/Issues/Process/Planning.md @@ -0,0 +1,39 @@ +--- +title: Issue Planning +description: Progressive Why, How, and What decomposition across issue altitudes. +--- + +# Issue Planning + +Issue planning adds detail progressively. Work starts with **Why**, gains an outcome-level **What**, and introduces only the **How** needed to decompose and deliver it. Detail increases toward ready delivery leaves; it is not copied upward before it is useful. + +## Planning altitudes + +| Native type | Why | How | What | +| --- | --- | --- | --- | +| [Epic](../Types/Epic.md) | States the strategic purpose and the outcome that advances an Initiative or objective. | Describes the outcome-level approach only far enough to identify coherent PBIs. | Defines the measurable aggregate result and its scope. | +| [PBI](../Types/PBI.md) | Explains why this bounded body of work contributes to its parent outcome. | Defines the delivery-level approach, interfaces, and decomposition into independently deliverable children. | Defines the bounded result and aggregate acceptance criteria. | +| [Task](../Types/Task.md) or [Bug](../Types/Bug.md) | Restates the local purpose so the delivery leaf is understandable on its own. | Records implementation decisions and the test-first execution plan. | Defines one concrete, verifiable deliverable sized for one pull request or one audited operational completion. | + +Every child retains enough local Why and acceptance criteria to be picked up independently. It references its parent's outcome instead of copying the parent's full body. + +## Ownership boundaries + +Issue planning connects canonical artifacts; it does not replace them: + +- [Goal Setting](../../Goal-Setting.md) owns Mission, OKR, and Initiative strategy. An Epic links delivery to that strategy. +- [Specifications](../../Spec-Driven-Development.md) own the durable Why and What of a capability. +- Designs own the durable technical How. +- Issues own the current decomposition, delivery decisions, readiness, and tracked work needed to close the gap between those artifacts and reality. + +Reference the owning artifact and capture only the local rationale required to understand the issue. When intent or design changes, update the canonical artifact first, then update affected issues and record the issue-body change in the audit trail. + +## Progressive decomposition + +1. Start at the highest issue that can state the outcome honestly. +2. Add just enough Why and What to establish scope and acceptance. +3. Introduce How when it is needed to choose boundaries, interfaces, or delivery slices. +4. Create native sub-issues for work that has independent outcomes or completion. +5. Continue until each leaf is a ready Task or Bug with one concrete deliverable. + +Decomposition does not create execution order by itself. Use [native dependency relationships](Relationships.md#execution-order) only where one item must finish before another can proceed; otherwise ready siblings remain eligible for parallel work. diff --git a/src/docs/Ways-of-Working/Issues/Process/Relationships.md b/src/docs/Ways-of-Working/Issues/Process/Relationships.md new file mode 100644 index 0000000..64e247b --- /dev/null +++ b/src/docs/Ways-of-Working/Issues/Process/Relationships.md @@ -0,0 +1,47 @@ +--- +title: Issue Relationships +description: Native containment, progress, dependency order, and parallel execution rules. +--- + +# Issue Relationships + +GitHub's native relationships are the authoritative issue graph. Prose may explain why a relationship exists, but it never recreates that graph. + +## Containment and progress + +Use native **sub-issues** to express that work is contained by an Epic, PBI, or nested PBI: + +- The parent owns the aggregate outcome. +- Each child owns a distinct slice with local purpose and acceptance criteria. +- The parent's progress is derived from the completion state of its native sub-issues. +- Containment does not imply execution order. + +Do not maintain a second child-link list in the parent body. The native sub-issue list is the current inventory and progress source. + +## Execution order + +Use native **blocked-by / blocking** relationships only when one issue must finish before another can proceed: + +- The waiting issue is blocked by the prerequisite. +- The prerequisite is blocking the waiting issue. +- Removing or changing the dependency updates the native edge. +- List position, numbering, creation time, and sub-issue order do not create a dependency. + +The native dependency graph is the source of truth for execution order. A checklist may describe work inside one delivery issue, but it does not order separate issues. + +## Parallel execution + +Ready siblings without dependency edges are eligible for parallel execution. Sharing a parent means they contribute to the same aggregate outcome; it does not make them sequential. + +Add a dependency edge only for a real prerequisite. Coordination, shared context, or a preferred review order may be explained in prose, but those preferences do not block otherwise ready work. + +## No duplicate relationship fields + +Do not add any of the following as relationship sources of truth: + +- Manual `Parent: #N` fields. +- Manual `Blocked by: #N` or `Blocking: #N` fields. +- Duplicated lists of child issue links. +- Statements that list position or numbering defines execution order. + +When a relationship changes, update the native relationship first. Then add a brief audit comment when the reason is not self-evident. Links in prose are appropriate for rationale or supporting context, not for maintaining a parallel containment or dependency model. diff --git a/src/docs/Ways-of-Working/Issues/Process/index.md b/src/docs/Ways-of-Working/Issues/Process/index.md index 1165302..10b0cfa 100644 --- a/src/docs/Ways-of-Working/Issues/Process/index.md +++ b/src/docs/Ways-of-Working/Issues/Process/index.md @@ -1,16 +1,19 @@ --- title: Issue Process -description: How issue bodies are structured and formatted. +description: How issue bodies, planning, lifecycle, and native relationships support delivery. --- # Issue Process -The universal rules for structuring and formatting issue bodies. +How issue bodies, planning, lifecycle, and native relationships support delivery. | Page | Description | | --- | --- | -| [Issue Format](Format.md) | The three-section issue structure, formatting, and labels. | +| [Issue Format](Format.md) | Universal title, body, audit, and formatting rules for every issue. | +| [Issue Lifecycle](Lifecycle.md) | How issue bodies, types, readiness, and relationships evolve through the workflow. | +| [Issue Planning](Planning.md) | Progressive Why, How, and What decomposition across issue altitudes. | +| [Issue Relationships](Relationships.md) | Native containment, progress, dependency order, and parallel execution rules. | 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/docs/Ways-of-Working/Issues/index.md b/src/docs/Ways-of-Working/Issues/index.md index 902a337..b77625d 100644 --- a/src/docs/Ways-of-Working/Issues/index.md +++ b/src/docs/Ways-of-Working/Issues/index.md @@ -11,7 +11,7 @@ Guidance for how issues are formatted and organized across the MSX ecosystem. | Section | Description | | --- | --- | -| [Issue Process](Process/index.md) | How issue bodies are structured and formatted. | +| [Issue Process](Process/index.md) | How issue bodies, planning, lifecycle, and native relationships support delivery. | | [Issue Types](Types/index.md) | The operational issue hierarchy from delivery work to strategic aggregation. | diff --git a/src/zensical.toml b/src/zensical.toml index f6b7b05..667f6f0 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -55,10 +55,17 @@ nav = [ {"Process" = [ "Ways-of-Working/Issues/Process/index.md", {"Format" = "Ways-of-Working/Issues/Process/Format.md"}, + {"Lifecycle" = "Ways-of-Working/Issues/Process/Lifecycle.md"}, + {"Planning" = "Ways-of-Working/Issues/Process/Planning.md"}, + {"Relationships" = "Ways-of-Working/Issues/Process/Relationships.md"}, ]}, {"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"},