Epic and PBI guidance describes consumer expectations

src/docs/Capabilities/agentic-development/agent-interaction.md

@@ -38,6 +38,11 @@ different runtime, or a person, weeks later.
 Intent MUST be recorded separately from implementation. The issue states *what* is wanted and
 *why*; the pull request proposes *how*.
 
+The canonical [issue planning altitude](../../Ways-of-Working/Issues/Process/Planning.md)
+governs the issue body. Task and Bug leaves retain technical decisions and test-first plans;
+the pull request contains the proposed implementation. Consumer-only aggregate guidance does
+not remove those delivery plans.
+
 The separation earns its keep at rejection. When a single artifact holds both, discarding a
 bad implementation discards the reasoning that motivated it, and the next attempt starts from
 nothing. When they are separate, the pull request closes and the issue stands — still stating
@@ -107,5 +112,5 @@ what happens next by looking at the artifact, without reconstructing a conversat
 - [Advisory Agents](advisory-agents.md) — how an agent publishes judgement onto these artifacts without taking authority.
 - [Automation Labels](../../Ways-of-Working/Automation-Labels.md) — the label vocabulary and ownership rules.
 - [Workflow](../../Ways-of-Working/Workflow.md) — the stages these artifacts move through.
-- [Issue Format](../../Ways-of-Working/Issues/index.md) — what an issue states.
+- [Issues](../../Ways-of-Working/Issues/index.md) and [Issue Planning](../../Ways-of-Working/Issues/Process/Planning.md) — issue discovery and type-specific intent and delivery planning.
 - [PR Format](../../Ways-of-Working/PR-Format.md) — what a pull request states.

src/docs/Coding-Standards/Documentation.md

@@ -51,7 +51,7 @@ This is a floor, not a ceiling. Internal and private units — helper functions
 
 ## The README is the front door
 
-Every repository has a README that is the single source of truth for what the repository is and does. It is **evergreen** — updated in the same pull request that changes behavior, never as a separate task. A feature that ships without a README update is not done.
+Every repository has a README that is the single source of truth for what the repository is and does. It is **evergreen** — kept current in the same pull request that changes behavior, never as a separate task. Relevant README content follows the shared [documentation and design evidence](../Ways-of-Working/Definition-of-Ready-and-Done.md#documentation-and-design-evidence) gate, including verification when it already describes the delivered result correctly.
 
 See [README-Driven Context](../Ways-of-Working/Readme-Driven-Context.md) for the full model.
 

src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md

@@ -13,7 +13,7 @@ Readiness is type-specific. The canonical type pages own the detailed criteria;
 
 ### Aggregate readiness
 
-An [Epic](Issues/Types/Epic.md#ready) or [PBI](Issues/Types/PBI.md#ready) is ready to decompose or coordinate when its aggregate outcome and acceptance criteria are testable, its native containment and dependency relationships are current, and no open decision prevents the first required children from becoming ready. Readiness does not send an aggregate into Build.
+An [Epic](Issues/Types/Epic.md#ready) or [PBI](Issues/Types/PBI.md#ready) is ready to decompose or coordinate when its [consumer expectations and scenarios](Issues/Process/Planning.md#consumer-expectations) are testable, its native containment and dependency relationships are current, and no open decision prevents the first required children from becoming ready. Readiness does not send an aggregate into Build or require a technical implementation plan in its body.
 
 ### Delivery-leaf readiness
 
@@ -47,16 +47,24 @@ Auto-merge gates only on what the ruleset declares. It waits for the required st
 
 Completion follows the issue's delivery or aggregate path. Across all paths, the issue's acceptance criteria are verified, required documentation is current, and no known regression is left implicit.
 
+### Documentation and design evidence
+
+Relevant current specifications, designs, and documentation MUST match the delivered consumer expectations and behavior. Update the owning artifacts when the change affects their requirements, technical approach, supported usage, or instructions. Verify affected examples, links, and instruction routes together so a reader reaches consistent, working guidance.
+
+Link the relevant document or anchor and record the verification in the delivery PR or operational audit evidence. If an existing design or document already describes the delivered result correctly, link it and explain why no update is needed; do not edit it solely to satisfy a checkbox. A missing artifact required by the change is work to complete, not evidence of an already-correct design.
+
+Aggregate completion verifies this evidence against the combined consumer outcome, not only against each child's isolated result. The [Documentation Model](Documentation-Model.md#why-what-how-a-home-for-everything) owns where each artifact lives; issue bodies and PRs carry completion evidence rather than copies of those artifacts.
+
 ### Repository delivery leaf
 
-A repository-delivery Task or Bug is done when its reviewed pull request is merged and closes that one leaf, required checks and tests pass, applicable coding standards hold, and the affected evergreen specification and documentation describe the delivered behavior. Release or deploy it where that applies.
+A repository-delivery Task or Bug is done when its reviewed pull request is merged and closes that one leaf, required checks and tests pass, applicable coding standards hold, and the [documentation and design evidence](#documentation-and-design-evidence) is complete. Release or deploy it where that applies.
 
 ### Operational Task
 
 An operational Task is done without a pull request only after the action has durable audit evidence, an independent verifier confirms every acceptance criterion, and the Task is closed. The canonical [operational delivery path](Issues/Types/Task.md#operational-delivery) owns the required record.
 
 ### Aggregate issue
 
-A PBI or Epic is done only when every required native child is complete and its own aggregate acceptance criteria and evidence are verified. Close the aggregate directly after that verification; a delivery pull request must not close it.
+A PBI or Epic is done only when every required native child is complete and its own aggregate acceptance criteria, combined behavior, and [documentation and design evidence](#documentation-and-design-evidence) are verified. Close the aggregate directly after that verification; a delivery pull request must not close it.
 
 Done is binary. Skip a criterion only when it genuinely does not apply. If "done" repeatedly needs exceptions, fix the definition rather than quietly lowering the bar.

src/docs/Ways-of-Working/Documentation-Model.md

@@ -104,6 +104,7 @@ with no reader, so a folder appears the first time it has something to hold
 | **What was explored** before deciding | the capability's **research** |
 | **How the work is done** — process, principles, conventions | [Ways of Working](index.md) |
 | **How code looks** — style applied to code | [Coding Standards](../Coding-Standards/index.md) |
+| **Which consumer outcome this work accepts** | the Epic or PBI; see [consumer expectations](Issues/Process/Planning.md#consumer-expectations) |
 | **How this one change is implemented** — paths, trade-offs | the Task or Bug delivery leaf and its PR; see [Issue Planning](Issues/Process/Planning.md) |
 
 Keeping implementation out of the spec is what makes the spec durable:
@@ -139,6 +140,8 @@ changes your understanding, so you amend them in place rather than treating the
 first draft as fixed. The gap between the spec and what the system actually does
 is the work.
 
+Completion follows the shared [documentation and design evidence](Definition-of-Ready-and-Done.md#documentation-and-design-evidence) gate. Update the owning artifact when the delivered result changes it; keep verification and justified no-change evidence in the delivery record instead of copying design or documentation into an aggregate issue.
+
 ## Evergreen and evolutionary
 
 Specs and designs are **evergreen**: written in the present tense as if the

src/docs/Ways-of-Working/Issues/Process/Format.md

@@ -21,11 +21,11 @@ The body is the current source of truth. It:
 
 - Explains the issue's local purpose and desired outcome without requiring prior context.
 - States observable acceptance criteria.
-- Records the decisions and plan needed at the issue's [planning altitude](Planning.md).
+- Uses the issue's [planning altitude](Planning.md): consumer scenarios for aggregates, technical decisions and executable plans for delivery leaves.
 - Links to durable specifications, designs, prior decisions, pull requests, or external references instead of duplicating them.
 - Changes as understanding, readiness, and scope change through the [issue lifecycle](Lifecycle.md).
 
-Keep information at its owning altitude. User-visible intent precedes technical detail, and implementation choices do not leak into outcome-level acceptance criteria. The type pages define which sections and evidence are required at each altitude.
+Keep information at its owning altitude. The canonical [consumer-expectation rule](Planning.md#consumer-expectations) governs Epic and PBI bodies; the type pages define the sections and evidence required at each altitude. Link the relevant documentation whose current behavior will be verified at completion.
 
 ## Native metadata and relationships
 

src/docs/Ways-of-Working/Issues/Process/Lifecycle.md

@@ -11,10 +11,10 @@ description: How issue bodies, types, readiness, and relationships evolve throug
 | --- | --- |
 | **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). |
+| **Plan** | Keep Epic and PBI bodies at the [consumer-expectation altitude](Planning.md#consumer-expectations); add technical decisions and test-first plans to Task and Bug leaves. Promote, demote, or split the issue when its scope requires a different type. Establish native 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. |
+| **Review** | Verify the delivered change against the leaf's current acceptance criteria and decisions, including the applicable parent consumer scenarios. Verify relevant design, documentation, and links through the [Definition of Done](../../Definition-of-Ready-and-Done.md#definition-of-done). 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, aggregate acceptance criteria, and documentation evidence satisfy the [Definition of Done](../../Definition-of-Ready-and-Done.md#definition-of-done). |
 | **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

@@ -1,39 +1,52 @@
 ---
 title: Issue Planning
-description: Progressive Why, How, and What decomposition across issue altitudes.
+description: Consumer expectations for Epics and PBIs, with technical test-first plans in Task and Bug delivery leaves.
 ---
 
 # 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.
+Issue planning separates consumer expectations from implementation. Epics and PBIs explain **Why** the work matters and **What** becomes observable for the consumer. Task and Bug delivery leaves add the technical **How** needed to deliver that result.
 
 ## Planning altitudes
 
-| Native type | Why | How | What |
+| Native type | Consumer need and motivation | Observable result | Technical planning |
 | --- | --- | --- | --- |
-| [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. |
+| [Epic](../Types/Epic.md) | The consumer problem and strategic outcome that advances an Initiative or objective. | Measurable aggregate expectations and scenarios at the repository's strategic scope. | Technical choices belong in the design and delivery leaves, not the Epic body. |
+| [PBI](../Types/PBI.md) | The consumer's bounded need and why it contributes to the parent outcome. | Acceptance scenarios for the combined behavior of its children. | Coordinate native children by outcome; keep implementation choices in the design and delivery leaves. |
+| [Task](../Types/Task.md) or [Bug](../Types/Bug.md) | Enough local consumer context to understand the delivery leaf independently. | One concrete, verifiable deliverable sized for one pull request or one audited operational completion. | Record implementation decisions, repository paths, interfaces, and the test-first execution plan. |
 
 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.
 
+## Consumer expectations
+
+Epics and PBIs MUST state the consumer's need, motivation, expectation, and observable behavior at their aggregate altitude. The consumer may be a user, integrator, operator, maintainer, or agent. Acceptance examples MUST describe a relevant context, an action or event, and a result the consumer or an independent verifier can observe. Use BDD-style Given / When / Then scenarios or an equally clear acceptance example; include failure or boundary cases where they distinguish the expected behavior.
+
+Epics and PBIs MUST NOT require architecture choices, solution-component inventories, repository file or function lists, or technical implementation checklists in their bodies. Consumer-facing contracts and genuine constraints may be named with their rationale, but they do not prescribe the internal solution. Apply the [spec/design altitude test](../../Spec-Driven-Development.md#what-a-specification-is): changing the implementation without changing the consumer expectation does not change aggregate acceptance.
+
+Scenarios clarify the need; they are not a second specification, a new test framework, or a separate BDD workflow. Link the relevant durable requirement and keep only the local context needed to understand this outcome. Task and Bug leaves retain technical decisions and translate the scenarios into the existing [test-first delivery plans](../../../Coding-Standards/Testing.md#test-first).
+
+For example, a PBI can require a complete repository inventory with no silent omissions. A Task may name the pagination helper, repository paths, and tests needed to deliver that behavior. A Bug may identify an observed truncation, its verified root cause, and the failing regression test before the fix. Those leaf-local plans do not become requirements in the parent PBI.
+
 ## 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.
+- [Designs](../../Spec-Driven-Development.md#what-a-design-is) own the durable technical How.
+- Epics and PBIs own consumer expectations, aggregate acceptance, readiness, and native outcome decomposition.
+- Task and Bug leaves own per-change implementation decisions and executable plans.
 
 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.
 
+Completion follows the shared [Definition of Done](../../Definition-of-Ready-and-Done.md#definition-of-done), including evidence that relevant design and documentation match the delivered expectations.
+
 ## 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.
+2. State the consumer's need and motivation, then use observable acceptance examples to establish scope.
+3. Separate meaningful consumer outcomes with native sub-issues; link the current design rather than prescribing it in the aggregate.
+4. Record technical choices and test-first execution steps in the Task or Bug that delivers each slice.
+5. Continue until each leaf is ready with one concrete deliverable and its documentation verification in scope.
 
 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.