📖 [Docs]: Issue planning, types, and relationships are defined

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.

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.

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.

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.
 
 <!-- INDEX:START -->
 
 | 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. |
 
 <!-- INDEX:END -->

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.

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.