📖 [Docs]: Native issue types now have dedicated guidance#93
Closed
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Closed
📖 [Docs]: Native issue types now have dedicated guidance#93Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
7 tasks
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 25, 2026 23:12
View session
There was a problem hiding this comment.
Pull request overview
Adds dedicated documentation pages for GitHub native issue types (Epic, PBI, Task, Bug) and refactors the existing hierarchy page to focus on shared taxonomy/routing, improving navigability and keeping “leaf” delivery guidance implementation-ready.
Changes:
- Added new guidance pages for Epic, PBI, Task, and Bug under
Ways-of-Working/Issues/Types/. - Simplified
Hierarchy.mdto shared hierarchy rules (taxonomy, routing, containment, promotion/demotion) and moved type-specific detail into the new pages. - Updated navigation (
zensical.toml) and regenerated the Types index to include the new pages.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| src/zensical.toml | Adds the four new issue-type pages to the “Issues → Types” navigation. |
| src/docs/Ways-of-Working/Issues/Types/index.md | Regenerated Types index to list the new pages with descriptions. |
| src/docs/Ways-of-Working/Issues/Types/Hierarchy.md | Reduced to concise shared hierarchy taxonomy/routing/promotion rules and links out to type pages. |
| src/docs/Ways-of-Working/Issues/Types/Epic.md | New Epic guidance page (strategy boundary, readiness, aggregate closure). |
| src/docs/Ways-of-Working/Issues/Types/PBI.md | New PBI guidance page (bounded outcomes, nested PBIs, readiness, aggregate closure). |
| src/docs/Ways-of-Working/Issues/Types/Task.md | New Task guidance page (implementation-ready leaf, test-first plan, repo vs operational completion). |
| src/docs/Ways-of-Working/Issues/Types/Bug.md | New Bug guidance page (observed/expected behavior, repro context, regression-test-first delivery). |
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 25, 2026 23:18
View session
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
July 25, 2026 23:20
Marius Storhaug (MariusStorhaug)
enabled auto-merge (squash)
July 25, 2026 23:20
This was referenced Jul 25, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 25, 2026 23:34
View session
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
6 tasks
Marius Storhaug (MariusStorhaug)
marked this pull request as draft
July 25, 2026 23:37
auto-merge was automatically disabled
July 25, 2026 23:37
Pull request was converted to draft
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 25, 2026 23:41
View session
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
July 25, 2026 23:42
Marius Storhaug (MariusStorhaug)
enabled auto-merge (squash)
July 25, 2026 23:42
Marius Storhaug (MariusStorhaug)
marked this pull request as draft
July 25, 2026 23:48
auto-merge was automatically disabled
July 25, 2026 23:48
Pull request was converted to draft
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Member
Author
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Jul 26, 2026
Issue guidance now explains how bodies, types, readiness, and native relationships evolve from capture through operation while keeping the Workflow page authoritative for phase definitions. ## New: Issue lifecycle, planning, and relationships The Process section now maps issue evolution onto the shared workflow, explains progressive Why/How/What decomposition, and establishes GitHub sub-issues and dependency edges as the authoritative containment and execution-order model. Ready siblings without dependency edges can proceed in parallel. ## New: Native issue type guidance Dedicated Epic, PBI, Task, and Bug pages now define the body detail, readiness, planning altitude, and completion rules for each native type. The shared hierarchy page focuses on taxonomy, routing, containment, and promotion or demotion. ## Changed: Universal issue format Issue Format now contains only rules shared by every native type and routes readers to the type-specific guidance. Manual relationship fields, copied child lists, and list-order sequencing are explicitly rejected. --- <details> <summary>Technical details</summary> - Added Lifecycle, Planning, and Relationships pages under `Issues/Process/`. - Reduced Format to universal title, body, metadata, audit, and Markdown rules. - Integrated the complete final Types guidance from PR #93 and preserved both Process and Types navigation subsections. - Consolidated Tasks #87 and #88 into this combined pull request after verifying the Types trees are identical. </details> <details> <summary>Relevant issues (or links)</summary> - Fixes #87 - Fixes #88 </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Native Epic, PBI, Task, and Bug guidance now gives contributors and agents a direct path from strategic aggregation to implementation-ready delivery.
Changed: Each native issue type has dedicated guidance
Epic connects a repository outcome to its Initiative and OKR, with measurable success, bounded scope, decomposition, readiness, and aggregate closure. PBI defines one bounded multi-deliverable outcome, including interfaces, nested decomposition, readiness, and aggregate closure.
Changed: Delivery leaves are implementation-ready
Task defines one planned deliverable with resolved decisions, a test-first one-pull-request plan, and an audited operational path when no repository artifact exists. Bug defines one correction with observed and expected behavior, reproduction context, a bounded root cause, and regression-test-first delivery. Multi-pull-request defects route through PBI children.
Changed: Hierarchy is a concise shared map
Hierarchy now owns only taxonomy, routing, native containment and dependencies, and promotion or demotion. Feature is explicitly temporary live metadata pending migration, never a planning altitude.
Technical details
Epic.md,PBI.md,Task.md, andBug.mdunder the Issue Types subtree.Hierarchy.md, regenerated the Types index, and changed only the Types subsection ofsrc/zensical.toml.main; the base-relative diff remains limited to the owned Types subtree and Types navigation subsection.Relevant issues (or links)