Repository navigation
Epic and PBI guidance describes consumer expectations - #230
Open
Marius Storhaug (MariusStorhaug) wants to merge 3 commits into
Open
Marius Storhaug (MariusStorhaug) wants to merge 3 commits into
Marius Storhaug (MariusStorhaug) wants to merge 3 commits into
Conversation
5 tasks done
There was a problem hiding this comment.
🟢 Approved
No active review issues block the documentation-only update separating consumer expectations from implementation planning.
No open issues 🎉
What changed in this PR
This documentation-only PR addresses #228 by separating Epic/PBI consumer expectations from Task/Bug implementation planning across the shared authoring and delivery guidance.
Changes:
- Defines consumer-focused acceptance scenarios for Epics and PBIs while preserving technical decisions and test-first plans in Tasks and Bugs.
- Adds shared completion evidence requirements for current design, documentation, examples, links, and instructions, allowing justified no-change evidence.
- Aligns workflow, template, README, and agent guidance while preserving native hierarchy and aggregate closure rules.
| File | Description |
|---|---|
| src/docs/Ways-of-Working/Workflow.md | Aligns planning, delivery, review, and closure with consumer expectations. |
| src/docs/Ways-of-Working/Workflow-Stages/Review.md | Adds the shared documentation evidence check. |
| src/docs/Ways-of-Working/Workflow-Stages/Implement.md | Reinforces test-first delivery and documentation verification. |
| src/docs/Ways-of-Working/Workflow-Stages/Define.md | Separates aggregate expectations from delivery-leaf technical plans. |
| src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md | Distinguishes durable artifact templates from issue plans. |
| src/docs/Ways-of-Working/Readme-Driven-Context.md | Requires README verification and updates only where needed. |
| src/docs/Ways-of-Working/Issues/Types/Task.md | Adds motivation and documentation verification while retaining technical plans. |
| src/docs/Ways-of-Working/Issues/Types/PBI.md | Adds consumer scenarios and combined-outcome completion evidence. |
| src/docs/Ways-of-Working/Issues/Types/Epic.md | Reframes strategic acceptance around observable consumer outcomes. |
| src/docs/Ways-of-Working/Issues/Types/Bug.md | Adds consumer context and documentation checks while preserving regression plans. |
| src/docs/Ways-of-Working/Issues/Process/Planning.md | Establishes canonical consumer-expectation and technical-planning boundaries. |
| src/docs/Ways-of-Working/Issues/Process/Lifecycle.md | Aligns planning, review, and shipping with the updated gates. |
| src/docs/Ways-of-Working/Issues/Process/index.md | Updates the planning page’s navigation description. |
| src/docs/Ways-of-Working/Issues/Process/Format.md | Routes issue bodies to type-appropriate content and evidence. |
| src/docs/Ways-of-Working/Issues/index.md | Adds a direct entry point to canonical planning guidance. |
| src/docs/Ways-of-Working/Documentation-Model.md | Clarifies artifact ownership and completion evidence placement. |
| src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md | Defines shared documentation and design evidence requirements. |
| src/docs/Coding-Standards/Documentation.md | Aligns README requirements with evidence-based verification. |
| src/docs/Capabilities/agentic-development/agent-interaction.md | Clarifies that intent separation preserves Task/Bug delivery plans. |
Review effort: Balanced
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
October 31, 2026 15:55
This was referenced Oct 31, 2026
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 1, 2026
PR Format describes the actual title and complete body: audience-first results, release-range-first analysis, complete adoption/compatibility evidence, one announcement boundary and conditional release decisions. Repository file policy is owned separately by Repository/Organization/Governance guidance, not by the PR Format page. Authors use canonical guidance for the resulting record. Repository standards exclude GitHub PR-template files from ordinary and central-default sources, while retaining other community defaults, genuine repository-specific contribution instructions and supported product-integration contracts. This delivery changes guidance and checks in MSXOrg/docs; separate owners remove their actual source/consumer files. No publisher, live caller, artifact, tag, governance setting or release history is changed here. <!-- ANNOUNCEMENT STOP --> ## Changed: PR Format focuses on the complete authored record Use one short reader-facing title and an audience-first summary, then ordered non-empty Breaking, Removed, New, Changed and Fixed results. Explain what changed, why, affected supported uses, compatibility and complete adoption actions or a justified no-action result in each result's prose. Keep prerequisites, ordering, verification and mandatory intermediate operations in the record itself, with supporting evidence and references scoped to the result they verify. The complete in-document example is named **Complete description example**. Its anchor is now `#complete-description-example`, replacing `#copy-the-complete-template`. The single announcement boundary and full body remain unchanged in purpose; announcements do not truncate the published note. Maintained links adopt the new anchor. Existing skills still route to the same canonical PR Format page and its release-coverage analysis; no additional skill, file distributor or plugin installation is required for this correction. PR Format contains no repository PR-template-file discussion: no file locations, copying/inheritance, local exceptions, presence/absence policy or deletion history. Those rules belong to the repository standards below. Product integration-template compatibility evidence remains distinct and required where a delivered result affects a supported integration. <details> <summary>Technical details</summary> | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | PR Format complete example, record evidence and anchors | Natural Language, Markdown, Documentation Model, PR Format | Complete consumer record and source-range authoring | Aligned | | Release Management result evidence | Specification/design separation, Markdown | Actual title/body/source coverage, retained product-integration compatibility | Aligned | | Repository-specific contribution PR-format links | Markdown, canonical ownership | Full description example; existing local build/index/link instructions | Aligned | | Record-format regression block | PowerShell/Pester, shared analyzer, testing baseline | Required structure, one boundary, five classifiers/evidence prompts and release-first order | Aligned | The tests separate record quality from repository file policy. Record tests verify the complete example and ordered classifiers, marker count, publication/candidate identity fields, five scoped release-evidence prompts, release-first analysis, and five affected-product integration prompts. They also reject GitHub PR-template-file discussion on this page without rejecting legitimate product integration contracts. File-policy tests inspect the owning repository/organization/governance pages, not PR Format. Five ownership/naming cases failed before the refinement and pass after it. The old example link is a documentation-anchor transition, not a runtime migration. Required old-to-new consumer actions still belong in the relevant release record; product docs retain supported target-state usage rather than a migration hierarchy or changelog. </details> ## Changed: Repository standards require canonical adherence without PR-template files Repository Standard owns the no-file rule for every MSX repository type and the special `MSXOrg/.github` and `PSModule/.github` sources. GitHub PR-template files, multiple-template directories, generated copies and local exceptions are not part of this contract. Organization Standard and Repository Governance reference that one owner; their former mandatory default-file rows and local PR-template exception are removed. Authors and validators verify the actual title, complete body, source coverage, compatibility/adoption evidence and normal review gates. An inherited scaffold, file-presence check or similarity to a central copy does not prove adherence. The complete canonical record example remains in the docs. Other code-of-conduct/security/support/contribution/issue-intake defaults and genuine repository-specific contribution instructions are unaffected; this is not an organization-wide community-file cleanup. Separate source and consumer owners remove existing PR-template files and revise their source docs/check expectations. This PR introduces no distributor, physically edits none of their workspaces and claims no pending deletion is merged. A missing file never substitutes for Markdown/source/head/containment validation or complete PR record quality. <details> <summary>Technical details</summary> | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Repository Standard no-file policy and PR/contribution guidance | Standard ownership, Markdown, Natural Language | One policy owner; canonical actual-record verification | Aligned | | Organization Standard community/review/default rows | Standard ownership, Markdown | Other community defaults preserved; PR-file requirements/exceptions removed | Aligned | | Repository Governance defaults and reconciliation evidence | Design ownership, Markdown | Required-source row removed without changing live controls | Aligned | | Markdown linter comment | YAML/Markdown standards | Only obsolete PR-template commentary changed; parsed configuration values are identical | Aligned | | Repository-policy regression block | PowerShell/Pester, source inventory | Own-policy links, no tracked PR file, case/extension/directory detection, unaffected issue forms | Aligned | The corrected regression checks were run against exported frozen guidance with no commits: five actual policy cases failed while eleven preservation/path cases passed. Current source checks recognize uppercase/lowercase PR file names, alternate extensions and multiple-template directories, while leaving issue forms and canonical PR Format docs unaffected. MSXOrg/docs contains no tracked GitHub PR-template file. Independent full, non-truncated default-source reads confirmed these **still-present** files at the measured immutable sources: | Repository | Source | File | | --- | --- | --- | | MSXOrg/.github | `0c67251812ea306543f3a14ab473ae357cfb76ac` | `.github/pull_request_template.md` | | PSModule/.github | `f424237c98b5b020f80e8c9563dbc37256fc1ec0` | `.github/pull_request_template.md` | | PSModule/Yml | `93d2656563a719d99416b9e13a05e65f6f815498` | `.github/pull_request_template.md` | | PSModule/PSSemVer | `1a621b14286331569f4d1ffd4643999c2a2a6ca8` | `.github/pull_request_template.md` | These are measured source/consumer counterexamples with separate removal owners, not evidence that the new no-file state has already landed. The Project's complete 71-repository inventory additionally identified the stale [PSModule/Template-PSModule#42](PSModule/Template-PSModule#42) candidate as separately owned reconciliation. [PSModule/Process-PSModule#525](PSModule/Process-PSModule#525) tracks the bounded producer anatomy/audit requirement reconciliation; central/default validators have separate owners. Their publisher/Build/runtime behavior remains outside this documentation revision. The [#231](#231) owner confirmed its clean frozen branch and no pending overlapping edits. The exact community composition boundary is the PR-template rows/paragraphs only: preserve its conditional local-contribution rule and all other inherited defaults while adopting the new no-file policy links. No #196/#208/#230/#231 tracked branch was edited here. </details> <details> <summary>Related references</summary> - Resolves [#226](#226) - References [#231](#231) - References [PSModule/Process-PSModule#525](PSModule/Process-PSModule#525) </details> ## Changed: Release-bound authoring starts from actual artifact publication Before drafting the title, results, adoption actions or compatibility decision, resolve the actual latest successful artifact publication for the same product, target and channel and verify its immutable source. Pin that artifact/source and the exact candidate PR source, verify intended lineage and compare those source trees. The complete delivered range includes earlier merged, skipped or unshipped changes; the ordinary PR-base diff remains separate implementation/reviewer evidence, not the note boundary. A GitHub Latest hint, moving tag, assumed highest version or overall failed run is not publication-baseline proof. Module publication to Gallery counts even when later GitHub completion fails: the next module record starts from its already-published source. Completing that older GitHub record does not make module changes new again. Multiple artifact targets/channels have independently pinned consumer baselines and applicability. Resolve missing/unverifiable evidence, ambiguous scope and diverged lineage explicitly. A verified initial publication has reviewed whole-candidate coverage and initial adoption instructions, not a fabricated predecessor or no-action/patch assumption. Re-read publication and candidate identities before readiness/snapshot capture and refresh comparison, actions and compatibility when either changes. This is the preserved authoring procedure, not a new publisher/version resolver or Build/artifact-promotion design. <details> <summary>Technical details</summary> | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Publication-baseline-first procedure, five result prompts and readiness | PR Format, Markdown | Exact publication/candidate identities, complete range and scoped PR diff | Aligned | | Release Management source binding and note evidence | Specification/design ownership | Actual artifact publication versus version/completion baselines | Aligned | | Thin PR-format skill and paired plugin metadata | Plugin granularity/versioning, manifest tests | Prior 0.1.1 canonical entrypoint retained | Aligned | The anonymous Git experiment remains exact source-tree evidence: published A-to-candidate C includes earlier unshipped B and current C, while scoped B-to-C includes only the current PR. Simulated Gallery-success/GitHub-failure evidence for B keeps module coverage at B-to-C even after older GitHub completion. Changed candidate/publication pairs change coverage, and unrelated lineage is rejected. Receipts were simulated inputs, not a live publish or historical repair. **Final committed/pushed head:** `bc03a5992615f65d1d5346dc48e7506e80b8b6ca`. This ordinary commit refines the previous `be8c340...` authoring correspondence without amendment or history discard. Canonical anchors are [release-first analysis](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/PR-Format.md#resolve-release-coverage-first), [complete description example](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/PR-Format.md#complete-description-example), [repository file policy](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/Repository-Standard.md#no-pr-template-files), and [defaults source guidance](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Capabilities/repository-governance/design.md#organization-defaults-repository). Local validation passes: all 80 Pester tests in seven suites, 127 documentation pages plus contribution-guide lint, indexes/relative anchors, seven cross-repository links, actual pinned Zensical 0.0.59 build and rendered new-anchor checks, zero PowerShell analyzer diagnostics, existing plugin-manifest validation, and patch checks. The parsed linter configuration remains unchanged. All five required hosted checks succeed on this exact head: [Lint](https://github.com/MSXOrg/docs/actions/runs/41243884162/job/124663205698), [Build](https://github.com/MSXOrg/docs/actions/runs/41243884162/job/124663205920), [Test](https://github.com/MSXOrg/docs/actions/runs/41243884162/job/124663205851), [Links](https://github.com/MSXOrg/docs/actions/runs/41243884162/job/124663205928), and [Cross-repository links](https://github.com/MSXOrg/docs/actions/runs/41243883939/job/124663204724). Both completed `pull_request` runs identify this source head. **Complete current-head review:** [5725019918](#209 (review)) is APPROVED on `bc03a5992615f65d1d5346dc48e7506e80b8b6ca`. The full summary records no active/open or suppressed concerns; all review threads are resolved and thread pagination is complete. The prior be8c340 approval was not used as approval of this correction. This is the automated author-side pass, not independent human approval or permission to merge. All five existing Task #226 plan items are fulfilled: verified state/cases, bounded canonical authoring, directly coupled policy/evidence/link reconciliation, native checks/current-head full review, and final acceptance/immutable handoff. The scoped sweep covered PR authoring, source/default validation, release/consumer and community guidance; only Task #226 is the closing delivery leaf. The existing native prerequisite [#166](#166) is completed. Its five-context required-check rule and the existing approval/thread constraints remain unchanged; no live merge attempt, injected failure or bypass was used. </details> ## Changed: Effective decisions and release-history ownership are preserved `DefaultBump` still accepts patch/minor/major with documented shared patch, repository settings, explicitly supplied supported caller overrides and one explicit owned bump override in that order. Omitted inputs inherit valid policy; invalid supplied settings and conflicting owned signals fail even when another source supplies a level. An effective default removes the need for a per-PR bump label, not the need for compatibility evidence. The exact owned set remains `release:patch`, `release:minor`, `release:major`, `release:prerelease` and `release:skip`. Verify actual native/shared producer controls or a supported adapter before using signals. Prerelease uses the resolved bump; skip combines with no other owned signal. Unmanaged routes omit all release metadata/labels; this repository deploys Pages without a versioned release artifact, so this PR retains neither a Release decisions block nor a release label. No undecided caller-override interface, allocator, publisher or live input is approved or implemented here. Complete PR/release records remain the sufficient version-specific upgrade history; resource docs describe supported target-state usage. Mandatory intermediate operations and superseded actions remain explicit. Campaign/native associations and completion-aware issue links retain their established ownership. No migration-guide/changelog duplication, date strategy, native dependency mutation, publication, historical backfill, label/permission/rules edit, merge or auto-merge is performed. <details> <summary>Technical details</summary> | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Automation Labels, settings/decision rules, VS Code and continuous-delivery guidance | Owning standards/capabilities | Accepted default/signal, source validation and native mapping retained | Aligned | | Documentation Model, Fleet, workflow/readiness and Task/Bug planning | Ways of Working, issue hierarchy, PR Format | Actual scoped implementation evidence and sufficient consumer record preserved | Aligned | The existing PRs stay separate on main. Eventual landing is one at a time with every remaining overlapping branch reconciled against advanced main and CI/full review repeated. Other owners must consume the refreshed immutable correspondence; their prior frozen example/file expectations are not claimed current. This PR does not edit their tracked candidates or waive their independent prerequisites. </details> <details> <summary>Related references</summary> - References [#196](#196) - References [#208](#208) - References [#230](#230) - References [#205](#205) - References [#166](#166) </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This branch has not been deployed
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.
Epic and PBI authors describe the consumer's need, motivation, expectation, and observable behavior instead of prescribing an implementation. Task and Bug authors retain technical decisions and test-first delivery plans. Completion verifies current design and documentation, updating affected content and recording evidence when it already matches the delivered result.
This changes guidance, not repository-inventory functionality, existing issue bodies, community files, or release automation. No new BDD tool, plugin reinstall, or configuration change is required.
Changed: Consumer expectations survive planning and completion
When authoring or deliberately refining an Epic or PBI, identify the consumer and motivation, then state observable acceptance examples using Given / When / Then or an equally clear scenario. Keep architecture choices, component inventories, file/function lists, and implementation checklists in the current design and Task/Bug delivery leaves. The issue skill and agent instruction route still reach one canonical issue-planning rule; they do not acquire a duplicate BDD process.
Completion verifies relevant current specifications, designs, documentation, examples, links, and instruction routes against delivered behavior. Update the owning artifacts where the change requires it. When an artifact already describes the result correctly, link it and record why no update is needed rather than editing it to satisfy a checkbox. Missing required documentation remains unfinished work. Native children still own aggregate progress, native dependencies still gate genuine prerequisites, and a delivery PR cannot close a PBI or Epic.
Technical details
The immutable delivery head contains three ordinary commits on a main-based topic branch. The complete diff changes 19 documentation pages and no plugin, workflow configuration, community file, legal/ownership file, or release record. The existing single issue-index skill pointer is unchanged, so the plugin version is not bumped.
Implementation-plan progress: all five #228 steps are complete: current-guidance comparison, representative scenarios and leaf counterexamples, canonical altitude/completion ownership, affected routes, and existing documentation checks plus complete-diff/summary review. The Task remains open until its reviewed PR is merged.
Validation and review: 64 existing Pester tests and 10 focused session checks pass. The focused checks detected the aggregate-authoring/completion contradictions before the edits and the missing README/agent routes before their correction. Generated indexes are current; documentation links resolve across 127 scanned files; all seven cross-repository links resolve; Markdown lint passes for all 19 changed pages; the actual Zensical site builds with no reported issues. Rendered HTML contains the new anchors and three Gherkin scenarios. All five live required checks—Build, Links, Test, Cross-repository links, and Lint—are successful at the immutable head. The explicitly requested Copilot round approved that exact head with zero new inline comments and no open review issues; complete diff, summary, and supporting evidence have been self-reviewed. No auto-merge is enabled.
Standards and framework alignment:
The existing repository README and thin client/skill routes remain correct for this change and are verified rather than churned. Spec-Driven Development already owns implementation-free durable requirements and technical designs; no second specification or BDD skill is added.
Composition and ownership: the release owner handed off the shared guidance pages. Read-only three-way compositions against complete #209 at
27ffab8ad89cf41147dc25ba2f6bd300b01b938f, #196 ate2e4b7d428badfce35e6511afd6aaedb77280613, and #208 at9f92fa1ad8f8f4d56e79f52a40acee09a3bdbad4all succeed. Each composition preserves exactly the same 19 changed paths and added/removed guidance lines; the complete PR Format scaffold remains byte-identical to its release candidate. Composed trees are435eb4220addb34c0c308318054cf48e09085507,40456e7f0d04707125ecc28e7fa6a0f045515858, anddc6888519fe271b0e36fce6e22b5561f4d6a17fb, respectively. No release changes are copied into this PR.The agreed human landing order is #209, #196, #208, this PR, then #229. Remaining branches need reconciliation and repeated CI/full review when main advances. Complete release-record/scaffold/conditional-decision and Task/Bug plan-progress contracts are preserved. No merge, retarget, native-dependency edit, or auto-merge action is performed.
Issue convergence: searches scoped to Epic/PBI, issue planning, and community/contribution identify #96, #154, and #229 as related but not fully delivered. #96 asks for broader removal of technical issue plans, contrary to this clarified Epic/PBI-only scope; #154 adds a separate premise-verification procedure; community inheritance stays in #229. Only #228 is closed by this PR; historical issues are not rewritten.
External intake follow-up: the Project will give separate narrow delivery surfaces to the inherited MSXOrg/.github Feature form and PSModule/.github Feature form. Their descriptions should ask for consumer need, motivation, and observable scenarios and link canonical issue planning and native-type routing instead of soliciting implementation framing. These source-owned intake forms are not copied or edited here; Bug forms, Task/Bug technical plans, and unrelated YAML/CI policy are preserved. #229 will use a separate coordinator-created issue session; this tracked workspace and PR remain scoped to #228.
The main documentation route builds and publishes the Zensical site; its two workflows do not invoke Release Management. Release-decision blocks and all
release:*labels are therefore absent. The title/description follows the complete handed-off #209 audience-first scaffold without changing that PR.Related references