📖 [Docs]: Issue guidance now follows the OKF structure (#91)

MariusStorhaug · Copilot · web-flow · commit 3e04c2607eca · 2026-07-25T22:36:47.000+02:00
Issue guidance is now organized under the OKF Issues section, with dedicated Process and Types navigation so readers and agents can drill directly into format or hierarchy guidance. ## Changed: Issue guidance follows the OKF structure The existing Issue Format and Issue Hierarchy pages retain their established guidance at their new canonical locations. All repository navigation and references now resolve through the indexed Issues subtree, and the retired top-level paths no longer exist. ## Technical Details - Added generated indexes for Issues, Issue Process, and Issue Types. - Relocated the two existing guidance pages without semantic expansion and adjusted only paths required by their new depth. - Updated Zensical navigation and every inbound repository link and anchor. - Implementation plan progress: all tasks in #89 are complete; local validation, CI, and the explicit Copilot review round are clean. <details> <summary>Related issues</summary> - Fixes #89 </details> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
diff --git a/src/docs/Agents/define.md b/src/docs/Agents/define.md
@@ -22,7 +22,7 @@ A description of a desired change, a feedback issue from a non-contributor (trea
 Turn the input into an issue with Section 1 (context and request).
 
 1. Search for duplicates first — propose consolidation rather than creating a new issue.
-2. Frame from the user's perspective per [Issue Format](../Ways-of-Working/Issue-Format.md).
+2. Frame from the user's perspective per [Issue Format](../Ways-of-Working/Issues/Process/Format.md).
 3. Acceptance criteria must be user-observable and testable.
 
 ### 2. Refine
@@ -38,8 +38,8 @@ Ground the issue so anyone reading it agrees on what "done" means, up to the [De
 
 Decide how the work will happen and record the decisions.
 
-1. **Task** — one deliverable, one pull request. Populate the technical decisions and the implementation plan per [Issue Format](../Ways-of-Working/Issue-Format.md).
-2. **Larger work** — decompose into child issues per [Issue Hierarchy](../Ways-of-Working/Issue-Hierarchy.md).
+1. **Task** — one deliverable, one pull request. Populate the technical decisions and the implementation plan per [Issue Format](../Ways-of-Working/Issues/Process/Format.md).
+2. **Larger work** — decompose into child issues per [Issue Hierarchy](../Ways-of-Working/Issues/Types/Hierarchy.md).
 3. Find the minimum viable path — spike, then proof of concept, then minimum viable product, then improve.
 4. Record decisions with their rationale and the alternatives considered.
 5. Resolve open questions before finishing; defer anything that does not block this slice to a follow-up issue.
@@ -54,5 +54,5 @@ Decide how the work will happen and record the decisions.
 ## Where this connects
 
 - [Workflow](../Ways-of-Working/Workflow.md) — the loop this opens.
-- [Issue Format](../Ways-of-Working/Issue-Format.md) and [Issue Hierarchy](../Ways-of-Working/Issue-Hierarchy.md) — issue structure and levels.
+- [Issue Format](../Ways-of-Working/Issues/Process/Format.md) and [Issue Hierarchy](../Ways-of-Working/Issues/Types/Hierarchy.md) — issue structure and levels.
 - [Definition of Ready and Done](../Ways-of-Working/Definition-of-Ready-and-Done.md) — the readiness bar this aims for.
diff --git a/src/docs/Agents/implement.md b/src/docs/Agents/implement.md
@@ -19,7 +19,7 @@ A Task issue number or URL with its three sections populated.
 
 ### 1. Orient
 
-1. Read the issue fully — all three sections per [Issue Format](../Ways-of-Working/Issue-Format.md).
+1. Read the issue fully — all three sections per [Issue Format](../Ways-of-Working/Issues/Process/Format.md).
 2. Read the repository README first per [README-Driven Context](../Ways-of-Working/Readme-Driven-Context.md).
 3. Identify the stack and load the relevant [Coding Standards](../Coding-Standards/index.md). Repo-local linter config wins where it disagrees with a published standard.
 
diff --git a/src/docs/Ways-of-Working/Branching-and-Merging.md b/src/docs/Ways-of-Working/Branching-and-Merging.md
@@ -33,7 +33,7 @@ Build the stack from its destination upward:
 
 Every layer follows the ordinary [Contribution Workflow](Contribution-Workflow.md):
 
-1. **Plan the dependency.** Give each layer its own Task issue. Record `Blocked by: #N` on dependent issues as described in [Issue Hierarchy](Issue-Hierarchy.md#how-to-express-the-hierarchy), and order the implementation so the shared foundation is the first layer.
+1. **Plan the dependency.** Give each layer its own Task issue. Record `Blocked by: #N` on dependent issues as described in [Issue Hierarchy](Issues/Types/Hierarchy.md#how-to-express-the-hierarchy), and order the implementation so the shared foundation is the first layer.
 2. **Open every layer as a draft.** After the initial commit, push the branch and open its pull request immediately. Use the standard user-facing title and description from [PR Format](PR-Format.md); do not add stack position or an internal branch name to the title.
 3. **Link the stack in Technical Details.** Add fully qualified pull request links for the immediate dependency and dependent, using `Depends on Owner/Repo#N` and `Followed by Owner/Repo#N`. Each pull request closes only its own Task issue.
 4. **Keep each delta isolated.** The pull request diff against its current base contains only that layer's change. Run its tests, checks, and automated review even when an earlier layer already exercised the combined code.
diff --git a/src/docs/Ways-of-Working/Contribution-Workflow.md b/src/docs/Ways-of-Working/Contribution-Workflow.md
@@ -11,7 +11,7 @@ Copilot on a **draft** pull request until it has no more feedback, then opens th
 pull request for people.
 
 This is the operational "how". The conventions it builds on live in the ways of
-working — [Issue Format](Issue-Format.md), [PR Format](PR-Format.md),
+working — [Issue Format](Issues/Process/Format.md), [PR Format](PR-Format.md),
 [Branching and Merging](Branching-and-Merging.md), and
 [Review Etiquette](Review-Etiquette.md).
 
@@ -87,7 +87,7 @@ For each piece of feedback, decide:
 - **In scope** — it concerns the change under review. Address it in this pull
   request and push; the next round re-checks it.
 - **Out of scope** — it points at a pre-existing gap or an adjacent improvement.
-  File an issue ([Issue Format](Issue-Format.md)) capturing the gap and reference
+  File an issue ([Issue Format](Issues/Process/Format.md)) capturing the gap and reference
   it; do not grow the pull request to cover it.
 - **Not actionable** — a false positive, or a matter of taste you disagree with.
   Reply with the reason and resolve the thread; a documented dismissal counts as
diff --git a/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md b/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md
@@ -11,7 +11,7 @@ Three gates bracket every piece of work: one gates when it can start, one gates
 
 An item is ready to be pulled into work when:
 
-- It is at the right level — a single deliverable, not a bundle. See [Issue Hierarchy](Issue-Hierarchy.md).
+- It is at the right level — a single deliverable, not a bundle. See [Issue Hierarchy](Issues/Types/Hierarchy.md).
 - The intent is clear — the problem and the desired outcome are understood, written from the user's perspective.
 - It has acceptance criteria — "done" is described and testable.
 - It is sized to fit comfortably within one cycle of work.
diff --git a/src/docs/Ways-of-Working/Documentation-Model.md b/src/docs/Ways-of-Working/Documentation-Model.md
@@ -27,7 +27,7 @@ mechanism, the moving parts, the configuration. Both are durable, and both
 evolve — neither is a one-time plan.
 
 Only the detail of a *single change* — the paths touched, the trade-off taken
-this once — stays out of both, living in the [issue](Issue-Format.md) and the
+this once — stays out of both, living in the [issue](Issues/Process/Format.md) and the
 pull request where it belongs.
 
 ## Capabilities live in folders
@@ -57,7 +57,7 @@ two documents live with the code.
 | **How / what** we build to deliver it | the capability's **design** |
 | **How we work** — process, principles, conventions | [Ways of Working](index.md) |
 | **How code looks** — style applied to code | [Coding Standards](../Coding-Standards/index.md) |
-| **How this one change is implemented** — paths, trade-offs | the [issue](Issue-Format.md) and the PR |
+| **How this one change is implemented** — paths, trade-offs | the [issue](Issues/Process/Format.md) and the PR |
 
 Keeping implementation out of the spec is what makes the spec durable:
 implementation detail rots fastest, so the spec leaves it to the design, and the
diff --git a/src/docs/Ways-of-Working/Fleet-Orchestration.md b/src/docs/Ways-of-Working/Fleet-Orchestration.md
@@ -132,7 +132,7 @@ flowchart TD
 ```
 
 1. **Queue the work.** Create a tracking issue per repository, with the campaign
-  prefix in the title and `stage:queued`, following the [Issue Format](Issue-Format.md).
+  prefix in the title and `stage:queued`, following the [Issue Format](Issues/Process/Format.md).
   The whole fleet starts as *Queued*. Skip this for any repository whose work
   item will be an **adopted pull request** (see step 2): that pull request is
   the work item and needs no tracking issue.
diff --git a/src/docs/Ways-of-Working/Goal-Setting.md b/src/docs/Ways-of-Working/Goal-Setting.md
@@ -32,7 +32,7 @@ OKRs are tracked as sub-issues of the Mission issue in the org `.github` reposit
 
 ## From strategy to delivery
 
-Initiatives are the bridge between strategy and execution. An Initiative is a sub-issue of an OKR and maps directly to an **Epic** in the relevant repository. From there it decomposes into PBIs and Tasks through the [Issue Hierarchy](Issue-Hierarchy.md).
+Initiatives are the bridge between strategy and execution. An Initiative is a sub-issue of an OKR and maps directly to an **Epic** in the relevant repository. From there it decomposes into PBIs and Tasks through the [Issue Hierarchy](Issues/Types/Hierarchy.md).
 
 ```text
 Mission (org-level, evergreen)
diff --git a/src/docs/Ways-of-Working/Issues/Process/Format.md b/src/docs/Ways-of-Working/Issues/Process/Format.md
@@ -233,9 +233,9 @@ Structure:
 - 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.
+- 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](Issue-Hierarchy.md).
+For PBIs and Epics, Section 3 is **a list of links to child issues**, not inline tasks. See [Issue Hierarchy](../Types/Hierarchy.md).
 
 **Example:**
 
@@ -408,4 +408,4 @@ Labels categorize. The category is never encoded in the title.
 | `Feature`   | Feature requests                                     |
 | `Question`  | Questions or discussion                              |
 
-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.
+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.
diff --git a/src/docs/Ways-of-Working/Issues/Process/index.md b/src/docs/Ways-of-Working/Issues/Process/index.md
@@ -0,0 +1,16 @@
+---
+title: Issue Process
+description: How issue bodies are structured and formatted.
+---
+
+# Issue Process
+
+The universal rules for structuring and formatting issue bodies.
+
+<!-- INDEX:START -->
+
+| Page | Description |
+| --- | --- |
+| [Issue Format](Format.md) | The three-section issue structure, formatting, and labels. |
+
+<!-- INDEX:END -->
diff --git a/src/docs/Ways-of-Working/Issues/Types/Hierarchy.md b/src/docs/Ways-of-Working/Issues/Types/Hierarchy.md
@@ -7,7 +7,7 @@ description: Delivery (Task or Bug), PBI, and Epic — the three operational lev
 
 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.
 
-Epics originate from Initiatives in the [Goal-Setting Framework](Goal-Setting.md).
+Epics originate from Initiatives in the [Goal-Setting Framework](../../Goal-Setting.md).
 
 ## Full hierarchy
 
@@ -104,7 +104,7 @@ Text-level conventions on child issues are courtesy duplicates of the native rel
 | 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).
+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
 
diff --git a/src/docs/Ways-of-Working/Issues/Types/index.md b/src/docs/Ways-of-Working/Issues/Types/index.md
@@ -0,0 +1,16 @@
+---
+title: Issue Types
+description: The operational issue hierarchy from delivery work to strategic aggregation.
+---
+
+# Issue Types
+
+How native issue types organize delivery and aggregation.
+
+<!-- INDEX:START -->
+
+| Page | Description |
+| --- | --- |
+| [Issue Hierarchy](Hierarchy.md) | Delivery (Task or Bug), PBI, and Epic — the three operational levels. |
+
+<!-- INDEX:END -->
diff --git a/src/docs/Ways-of-Working/Issues/index.md b/src/docs/Ways-of-Working/Issues/index.md
@@ -0,0 +1,17 @@
+---
+title: Issues
+description: How issues are formatted and organized across the MSX ecosystem.
+---
+
+# Issues
+
+Guidance for how issues are formatted and organized across the MSX ecosystem.
+
+<!-- INDEX:START -->
+
+| Section | Description |
+| --- | --- |
+| [Issue Process](Process/index.md) | How issue bodies are structured and formatted. |
+| [Issue Types](Types/index.md) | The operational issue hierarchy from delivery work to strategic aggregation. |
+
+<!-- INDEX:END -->
diff --git a/src/docs/Ways-of-Working/Spec-Driven-Development.md b/src/docs/Ways-of-Working/Spec-Driven-Development.md
@@ -18,7 +18,7 @@ A change moves down a ladder of artifacts. Each sits at a fixed altitude, is ver
 | **Need** | Is this worth doing? | one line | the request or issue | — |
 | **Spec** | Why, what, for whom, and what "done" means | implementation-agnostic | the capability folder, in the owning repo | intent changes |
 | **Design** | How it is built | technical, still readable | beside its spec (`design.md`) | the approach changes |
-| **Tasks** | In what steps | actionable | issues, at the levels of the [issue hierarchy](Issue-Hierarchy.md) | the plan changes |
+| **Tasks** | In what steps | actionable | issues, at the levels of the [issue hierarchy](Issues/Types/Hierarchy.md) | the plan changes |
 | **Code & tests** | The working expression | concrete | the codebase | continuously |
 
 ```mermaid
@@ -56,7 +56,7 @@ A spec **excludes** — this is the design's job:
 - The task breakdown and rollout sequence.
 - Links to the code that fulfils it — implementations come and go.
 
-The altitude test: push detail *down* into the design, and push scope *up* into the epic. If a sentence would change when the team picks a different library, it belongs in the design, not the spec. This is the same rule the [Issue Format](Issue-Format.md) applies to issues — describe the *what* and *why*, never the *how*.
+The altitude test: push detail *down* into the design, and push scope *up* into the epic. If a sentence would change when the team picks a different library, it belongs in the design, not the spec. This is the same rule the [Issue Format](Issues/Process/Format.md) applies to issues — describe the *what* and *why*, never the *how*.
 
 ## Specify the minimum
 
@@ -112,7 +112,7 @@ The method is requirements-first. Work does not start from a solution; it starts
 2. **Draft the spec.** Capture the why, the outcome, and the requirements collaboratively. Agents draft, research context, and check the spec for ambiguity and gaps; humans supply the intent and make the calls ([AI-first development](Principles/AI-First-Development.md)). Unknowns are marked, not guessed (see [Authoring conventions](#authoring-conventions)).
 3. **Review the spec as a pull request.** The spec is versioned and reviewed like any change, following [PR Format](PR-Format.md) and [Review Etiquette](Review-Etiquette.md). Review argues about intent while it is still cheap to change.
 4. **Pass the readiness bar.** The spec is ready when it meets the [Definition of Ready](Definition-of-Ready-and-Done.md#definition-of-ready) — clear intent, testable acceptance criteria, no open questions that would change the approach.
-5. **Design and decompose.** Write the design, then break the work into the levels of the [issue hierarchy](Issue-Hierarchy.md) — an epic into smaller, independently deliverable items.
+5. **Design and decompose.** Write the design, then break the work into the levels of the [issue hierarchy](Issues/Types/Hierarchy.md) — an epic into smaller, independently deliverable items.
 6. **Build against the spec.** Implement in thin vertical slices, test-first where it pays, to the [Definition of Done](Definition-of-Ready-and-Done.md#definition-of-done) ([engineering practices](Principles/Engineering-Practices.md)). [Test-driven development](Principles/Engineering-Practices.md#test-driven-development) is an implementation practice governed by the coding standards and the Definition of Done, not something each spec re-specifies.
 7. **Feed reality back.** Metrics and incidents update the spec, and the cycle repeats.
 
@@ -134,7 +134,7 @@ Splitting the spec from the design is what lets the spec stay stable across refa
 - **Self-review against a checklist.** Before review, confirm the spec is complete: no clarification markers remain, every requirement is testable, and the success criteria are measurable — a checklist is a unit test for the English.
 - **Keep it navigable.** The spec is readable in one sitting. Heavy detail moves into the design or a linked note, not the body.
 - **Reference, do not restate.** Point at the canonical standard or guide rather than copying it, so there is one source of truth and no drift.
-- **Links, not bare URLs.** Every external reference is a Markdown link, scoped the same way as in the [Issue Format](Issue-Format.md).
+- **Links, not bare URLs.** Every external reference is a Markdown link, scoped the same way as in the [Issue Format](Issues/Process/Format.md).
 
 ## Templates
 
diff --git a/src/docs/Ways-of-Working/Workflow.md b/src/docs/Ways-of-Working/Workflow.md
@@ -61,7 +61,7 @@ A desire for change enters the system. It can come from anywhere:
 The goal is to **write it down** — quickly, in a GitHub issue — so it exists for the world to see and "remember".
 At this stage, precision is less important than existence. The issue captures the current state, the pain or opportunity, and the desired outcome.
 
-See [Issue Format § Section 1](Issue-Format.md) for structure.
+See [Issue Format § Section 1](Issues/Process/Format.md) for structure.
 
 ### Refine
 
@@ -88,7 +88,7 @@ Turn the refined understanding into actionable work:
 
 The plan is the contract. It drives implementation.
 
-See [Documentation Model](Documentation-Model.md), [Issue Format § Sections 2–3](Issue-Format.md), [Issue Hierarchy](Issue-Hierarchy.md).
+See [Documentation Model](Documentation-Model.md), [Issue Format § Sections 2–3](Issues/Process/Format.md), [Issue Hierarchy](Issues/Types/Hierarchy.md).
 
 ### Build
 
diff --git a/src/docs/Ways-of-Working/index.md b/src/docs/Ways-of-Working/index.md
@@ -30,8 +30,7 @@ This section documents the principles, processes, and norms that every contribut
 | [Engineering Taste](Engineering-Taste.md) | The judgment that takes over when the standards run out. |
 | [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) | Delivery (Task or Bug), PBI, and Epic — the three operational levels. |
+| [Issues](Issues/index.md) | How issues are formatted and organized across the MSX ecosystem. |
 | [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. |
diff --git a/src/zensical.toml b/src/zensical.toml
@@ -50,8 +50,17 @@ nav = [
     {"Engineering Taste" = "Ways-of-Working/Engineering-Taste.md"},
     {"Goal-Setting Framework" = "Ways-of-Working/Goal-Setting.md"},
     {"Definition of Ready and Done" = "Ways-of-Working/Definition-of-Ready-and-Done.md"},
-    {"Issue Format" = "Ways-of-Working/Issue-Format.md"},
-    {"Issue Hierarchy" = "Ways-of-Working/Issue-Hierarchy.md"},
+    {"Issues" = [
+      "Ways-of-Working/Issues/index.md",
+      {"Process" = [
+        "Ways-of-Working/Issues/Process/index.md",
+        {"Format" = "Ways-of-Working/Issues/Process/Format.md"},
+      ]},
+      {"Types" = [
+        "Ways-of-Working/Issues/Types/index.md",
+        {"Hierarchy" = "Ways-of-Working/Issues/Types/Hierarchy.md"},
+      ]},
+    ]},
     {"PR Format" = "Ways-of-Working/PR-Format.md"},
     {"Commit Conventions" = "Ways-of-Working/Commit-Conventions.md"},
     {"Branching and Merging" = "Ways-of-Working/Branching-and-Merging.md"},
