Skip to content

Express Epic and PBI issues as consumer expectations #228

Description

Context and request

Authors and consumers of Epics and PBIs need issues to explain the consumer's need, expectation, and observable outcome rather than prescribe solution components or implementation checklists. The user confirmed a behavior-driven style for these aggregate types only; Tasks and Bugs retain their technical decisions and executable plans.

Acceptance criteria

  • Epic/PBI guidance and examples describe consumer context, motivation, and observable scenarios at the appropriate altitude, without requiring architecture choices, file/function lists, or technical implementation plans in their bodies.
  • Task/Bug guidance still includes consumer outcomes plus technical decisions, test-first plans, and evidence appropriate to a delivery leaf.
  • Completion requires relevant design/documentation to reflect the delivered behavior, be updated where needed, and have aligned working links/instructions; an already-correct design is evidenced rather than churned.
  • Issue planning/type/readiness pages, documentation templates, workflows, and the thin issue skill/instruction routes agree on those boundaries with one canonical process.
  • Native hierarchy and aggregate completion remain valid, and existing documentation validation and complete review pass.

Technical decisions

Deliver one focused standards PR in MSXOrg/docs. Reconcile the Issues process/type pages, planning/readiness/completion guidance, documentation ownership and templates, and dependent thin pointers without duplicating a BDD process or creating another skill. Preserve the release communication contract already prepared in PR #209; do not fold this independent change into #209/#196/#208. Repository-specific community guidance is separate work, not permission for fleet file cleanup.

Implementation plan

  • Compare current Epic/PBI/Task/Bug authoring examples and identify altitude contradictions before editing.
  • Establish representative consumer scenarios plus Task/Bug technical-plan counterexamples.
  • Align canonical issue/type/planning guidance and completion/documentation ownership while preserving native delivery-leaf mechanics.
  • Reconcile all affected workflow/template/skill links and instructions with the owning pages.
  • Run existing documentation checks and full review; record the expected consumer behavior and preserved delivery-plan evidence in the PR.

Activity

  1. MariusStorhaug commented on Oct 31, 2026

    @MariusStorhaug
    MemberAuthor

    Marked the comparison and representative-scenario steps complete after the first scoped commit fd40779. The pre-change checks detected the aggregate technical-section/planning contradictions, while Task/Bug technical plans and native leaf behavior remained valid. The consumer checks now pass; documentation/design completion and final review steps remain in progress in #230. No historical issues or release PRs were rewritten.

  2. MariusStorhaug commented on Oct 31, 2026

    @MariusStorhaug
    MemberAuthor

    Marked the canonical guidance and affected-route steps complete at 1c8f98c. The shared completion gate requires current design/documentation plus working examples, links, and instructions, and accepts evidence for already-correct artifacts instead of mandatory edits. Ten focused checks pass, including retained Task/Bug technical plans and native aggregate mechanics. Read-only composition with the release-owner candidate #209 at 27ffab8 is clean; no release changes were copied into this PR. The thin issue skill/plugin is unchanged. Final CI/Copilot and summary review remain open; #229 is separate.

  3. MariusStorhaug commented on Oct 31, 2026

    @MariusStorhaug
    MemberAuthor

    Completed the final verification/review step at 1c8f98c. All five required GitHub checks are successful, 64 existing Pester tests and 10 focused checks pass, index/link/Markdown/site validation passes, and the explicitly requested Copilot round approved the exact head with zero new inline comments or open issues. Complete diff, PR summary, and evidence have been self-reviewed. Read-only composition against all three immutable release candidates preserves exactly the 19-path consumer-guidance delta and leaves their complete PR scaffold unchanged. #230 is being handed to human review without merging or enabling auto-merge; this Task remains open until merge. #229 and the two source-owned Feature intake forms have separate coordinator-owned delivery surfaces.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions