diff --git a/src/docs/Capabilities/agentic-development/agent-interaction.md b/src/docs/Capabilities/agentic-development/agent-interaction.md index 098f3cea..ef9ed3b5 100644 --- a/src/docs/Capabilities/agentic-development/agent-interaction.md +++ b/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. diff --git a/src/docs/Coding-Standards/Documentation.md b/src/docs/Coding-Standards/Documentation.md index f74afbc6..dd9caf69 100644 --- a/src/docs/Coding-Standards/Documentation.md +++ b/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. 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 index fe00242d..fe57d211 100644 --- a/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md +++ b/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,9 +47,17 @@ 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 @@ -57,6 +65,6 @@ An operational Task is done without a pull request only after the action has dur ### 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. diff --git a/src/docs/Ways-of-Working/Documentation-Model.md b/src/docs/Ways-of-Working/Documentation-Model.md index 9bd9c2c6..201ec474 100644 --- a/src/docs/Ways-of-Working/Documentation-Model.md +++ b/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) | | **What a release changes, why, and how consumers align** | its source-bound release record, authored in the release-bound PR; see [PR Format](PR-Format.md) | @@ -140,6 +141,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 diff --git a/src/docs/Ways-of-Working/Issues/Process/Format.md b/src/docs/Ways-of-Working/Issues/Process/Format.md index 1117ba82..24a8df98 100644 --- a/src/docs/Ways-of-Working/Issues/Process/Format.md +++ b/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 diff --git a/src/docs/Ways-of-Working/Issues/Process/Lifecycle.md b/src/docs/Ways-of-Working/Issues/Process/Lifecycle.md index 476a5011..5d7f7a95 100644 --- a/src/docs/Ways-of-Working/Issues/Process/Lifecycle.md +++ b/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. diff --git a/src/docs/Ways-of-Working/Issues/Process/Planning.md b/src/docs/Ways-of-Working/Issues/Process/Planning.md index 23d9b0bc..ed7e2c4f 100644 --- a/src/docs/Ways-of-Working/Issues/Process/Planning.md +++ b/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. diff --git a/src/docs/Ways-of-Working/Issues/Process/index.md b/src/docs/Ways-of-Working/Issues/Process/index.md index 10b0cfaf..ee4ad403 100644 --- a/src/docs/Ways-of-Working/Issues/Process/index.md +++ b/src/docs/Ways-of-Working/Issues/Process/index.md @@ -13,7 +13,7 @@ How issue bodies, planning, lifecycle, and native relationships support delivery | --- | --- | | [Issue Format](Format.md) | Universal title, body, audit, and formatting rules for every issue. | | [Issue Lifecycle](Lifecycle.md) | How issue bodies, types, readiness, and relationships evolve through the workflow. | -| [Issue Planning](Planning.md) | Progressive Why, How, and What decomposition across issue altitudes. | +| [Issue Planning](Planning.md) | Consumer expectations for Epics and PBIs, with technical test-first plans in Task and Bug delivery leaves. | | [Issue Relationships](Relationships.md) | Native containment, progress, dependency order, and parallel execution rules. | diff --git a/src/docs/Ways-of-Working/Issues/Types/Bug.md b/src/docs/Ways-of-Working/Issues/Types/Bug.md index bdbed038..e0648398 100644 --- a/src/docs/Ways-of-Working/Issues/Types/Bug.md +++ b/src/docs/Ways-of-Working/Issues/Types/Bug.md @@ -15,6 +15,7 @@ Follow the universal [Issue Format](../Process/Format.md), with these Bug-specif ### Context and request +- **Consumer context:** who is affected and why the correction matters. - **Observed behavior:** what happens, including exact errors, outputs, or impact. - **Expected behavior:** the observable result that should occur instead. - **Reproduction:** the smallest repeatable steps, inputs, and commands. @@ -34,11 +35,13 @@ Follow the universal [Issue Format](../Process/Format.md), with these Bug-specif Start by reproducing the failure in an automated regression test. Then implement the smallest root-cause correction, run the affected and broader test surfaces, and update relevant documentation. If automation is genuinely impossible, record the reason and an equivalent repeatable verification before implementation. +Include verification of the relevant current design, documentation, and working instructions through the shared [completion evidence gate](../../Definition-of-Ready-and-Done.md#documentation-and-design-evidence). Root-cause decisions and executable regression plans remain in this delivery leaf, not its parent aggregate. + ## Ready A Bug is implementation-ready when: -- observed and expected behavior, reproduction, environment, regression status, workaround, and acceptance criteria are explicit; +- consumer context, observed and expected behavior, reproduction, environment, regression status, workaround, and acceptance criteria are explicit; - the correction is bounded to one pull request; - the root-cause boundary and unresolved hypotheses are clear enough to prevent scope drift; - dependencies and blockers are known; and diff --git a/src/docs/Ways-of-Working/Issues/Types/Epic.md b/src/docs/Ways-of-Working/Issues/Types/Epic.md index 7ba7377d..ac050f9d 100644 --- a/src/docs/Ways-of-Working/Issues/Types/Epic.md +++ b/src/docs/Ways-of-Working/Issues/Types/Epic.md @@ -13,11 +13,11 @@ Use an Epic when the work connects strategy to several bounded bodies of work. U An Initiative is an organization-level bet under an OKR; an Epic is that Initiative's repository-level delivery aggregate. Link the Initiative and relevant OKR rather than copying their full bodies. When an Initiative spans repositories, each repository owns the Epic for its part of the outcome. -The Epic states the repository contribution through the Golden Circle: +The Epic states the repository contribution at the [consumer-expectation altitude](../Process/Planning.md#consumer-expectations): -- **Why:** the problem, strategic objective, and Key Result this work is expected to move. -- **How:** the capability-level approach and boundaries, without implementation detail. -- **What:** the observable repository outcomes the child PBIs collectively deliver. +- **Consumer and need:** who is affected and what they need to achieve. +- **Motivation:** the problem, strategic objective, and Key Result this work is expected to move. +- **Expectation:** the observable repository outcomes the child PBIs collectively deliver, not the components used to deliver them. ## Issue body @@ -26,33 +26,44 @@ Follow the universal [Issue Format](../Process/Format.md), with these Epic-speci ### Context and request - Link the parent Initiative and relevant OKR. -- State the strategic outcome through Why, How, and What. +- Identify the consumer, their need, and why the strategic outcome matters to them. - Define success measures with a baseline or current state, a target, and how the result will be observed. - Bound the in-scope and out-of-scope outcomes. -- Write aggregate acceptance criteria that prove the PBIs combine into the intended outcome. +- Link relevant current specifications and designs rather than restating them. -### Technical decisions +### Consumer scenarios -- Record the chosen scope boundaries and significant trade-offs. -- Explain the decomposition into PBIs and why each boundary is independently meaningful. -- Identify interfaces, ownership boundaries, dependencies, and sequencing between PBIs. -- Keep implementation decisions in the child PBI, Task, or Bug where they can be made at the right altitude. +Write aggregate acceptance examples that prove the PBIs combine into the intended consumer outcome. Keep them at strategic scope, with success measures that an independent verifier can observe. -### Implementation plan +For example, maintainers need to trust repository coverage before deciding where to improve fleet health: -Use native sub-issues for the child PBIs. The plan may summarize those links and their intended outcomes, but it does not contain an inline implementation checklist. +```gherkin +Scenario: Maintainers can trust fleet coverage + Given maintainers manage repositories across several organizations + When they assess fleet health + Then every repository in the agreed scope is accounted for + And any gap in coverage is explicit before they act on the result +``` + +The Epic names the coverage baseline, target, and observation method; it does not require a service, dashboard, library, or file layout. + +### Scope and coordination + +Explain meaningful outcome boundaries and constraints only where they help coordinate the work. Use native sub-issues for child PBIs and native dependencies for genuine prerequisites. The native graph owns inventory and progress; do not copy a child-link list into the body. Technical choices stay in the linked design and Task or Bug leaves. ## Ready An Epic is ready for decomposition when: - the Initiative and OKR relationship is linked and the repository boundary is clear; -- Why, How, What, success measures, scope, and aggregate acceptance criteria are explicit; -- the initial PBI boundaries, interfaces, dependencies, and ownership are understood; and +- the consumer need, motivation, success measures, scope, and aggregate scenarios are explicit; +- the initial PBI outcome boundaries and native relationships are understood; and - no open decision prevents the first PBIs from becoming ready. ## Aggregate closure Close an Epic only when every required child PBI is complete, the aggregate acceptance criteria are verified, and the success measures have current evidence. Move any intentionally deferred outcome to a linked follow-up before closure. Record the final evidence in the Epic; do not close it through a direct implementation pull request. +Verify the relevant design, documentation, and their links through the shared [Definition of Done](../../Definition-of-Ready-and-Done.md#definition-of-done), including the combined consumer outcome rather than only each child's evidence. + See the [Goal-Setting Framework](../../Goal-Setting.md) for the Mission, OKR, and Initiative model and the [Issue Hierarchy](Hierarchy.md) for containment and routing. diff --git a/src/docs/Ways-of-Working/Issues/Types/PBI.md b/src/docs/Ways-of-Working/Issues/Types/PBI.md index 16721842..ac3c02e7 100644 --- a/src/docs/Ways-of-Working/Issues/Types/PBI.md +++ b/src/docs/Ways-of-Working/Issues/Types/PBI.md @@ -11,25 +11,40 @@ Use a PBI when the outcome needs more than one pull request or independently com ## Issue body -Follow the universal [Issue Format](../Process/Format.md), with these PBI-specific contents. +Follow the universal [Issue Format](../Process/Format.md) and canonical [consumer-expectation altitude](../Process/Planning.md#consumer-expectations), with these PBI-specific contents. ### Context and request -- State one bounded user, operator, or maintainer outcome. +- Identify the consumer, their bounded need, and why meeting it matters. +- State the expected observable behavior and its contribution to the parent outcome. - Define in-scope and out-of-scope boundaries. -- Write aggregate acceptance criteria that verify the children work together, not criteria copied from each child. - Identify constraints and dependencies that affect the whole body of work. +- Link relevant current specifications and designs rather than restating them. -### Technical decisions +### Consumer scenarios -- Explain the decomposition into Tasks, Bugs, or nested PBIs. -- Define interfaces, contracts, ownership boundaries, and integration points between children. -- Record cross-child sequencing with native blocked-by relationships; containment alone does not imply order. -- Keep child-local implementation decisions in the child issue. +Write aggregate acceptance examples that verify the children work together for the consumer, not implementation criteria copied from each child. -### Implementation plan +For example, a maintainer needs a complete repository inventory so their checks do not silently miss work: -Use native sub-issues for every delivery child. The plan may summarize the linked children and their outcomes, but it does not replace them with an inline implementation checklist. +```gherkin +Scenario: The default inventory is complete + Given a caller can access 137 repositories + When they request an inventory without an explicit limit + Then all 137 repositories appear exactly once + +Scenario: Incomplete coverage is not presented as success + Given one repository in the requested scope cannot be read + When a caller requests the inventory + Then the failure is explicit + And a partial inventory is not presented as complete +``` + +Pagination helpers, internal interfaces, file paths, and implementation steps belong in the design and delivery leaves, not these acceptance examples. + +### Scope and coordination + +Explain the consumer outcome boundaries that justify Tasks, Bugs, or nested PBIs. Use native sub-issues for every delivery child and native blocked-by relationships for genuine prerequisites; containment alone does not imply order. Do not duplicate the native child inventory in the body or turn coordination into an implementation checklist. ## Nested PBIs @@ -41,8 +56,8 @@ A defect that needs multiple pull requests is a PBI, not an oversized Bug. Decom A PBI is ready for delivery when: -- the bounded outcome, scope, and aggregate acceptance criteria are testable; -- interfaces, dependencies, and integration expectations are explicit; +- the consumer need, motivation, bounded outcome, scope, and aggregate scenarios are testable; +- consumer-facing constraints, native dependencies, and combined behavior expectations are explicit; - the work is decomposed far enough that the first delivery children meet their own readiness gates; and - no unresolved decision would materially change the child boundaries. @@ -50,4 +65,6 @@ A PBI is ready for delivery when: Close a PBI only when every required child is complete and the aggregate acceptance criteria have been verified across their combined output. Move deferred work to linked follow-ups and record integration or operational evidence in the PBI. A PBI does not own a direct implementation branch or closing pull request. +Verify the relevant design, documentation, and their links against that combined output through the shared [Definition of Done](../../Definition-of-Ready-and-Done.md#definition-of-done). + See the [Issue Hierarchy](Hierarchy.md) for containment, routing, and promotion or demotion. diff --git a/src/docs/Ways-of-Working/Issues/Types/Task.md b/src/docs/Ways-of-Working/Issues/Types/Task.md index 745edbc0..71de4800 100644 --- a/src/docs/Ways-of-Working/Issues/Types/Task.md +++ b/src/docs/Ways-of-Working/Issues/Types/Task.md @@ -15,7 +15,7 @@ Follow the universal [Issue Format](../Process/Format.md), with these Task-speci ### Context and request -- State the single user, operator, or maintainer outcome. +- State the single user, operator, or maintainer outcome and why it matters. - Write observable, testable acceptance criteria for that deliverable. - Identify constraints, dependencies, and explicit non-goals. - Link the parent PBI or Epic when the Task is part of an aggregate. @@ -31,6 +31,8 @@ Follow the universal [Issue Format](../Process/Format.md), with these Task-speci Write an actionable checkbox plan at repository-path and behavior level. For each behavior, put the test or verification step before its implementation step, following the [test-first standard](../../../Coding-Standards/Testing.md#test-first). Include documentation and final validation in the same plan. +Identify the relevant current design and documentation to verify through the shared [completion evidence gate](../../Definition-of-Ready-and-Done.md#documentation-and-design-evidence). Keep repository paths and technical steps here even when the parent uses consumer scenarios. + The checklist describes one pull request. If it reveals independent deliverables, promote the issue to a PBI and create delivery children. ## Ready diff --git a/src/docs/Ways-of-Working/Issues/index.md b/src/docs/Ways-of-Working/Issues/index.md index b77625d8..7f78e47a 100644 --- a/src/docs/Ways-of-Working/Issues/index.md +++ b/src/docs/Ways-of-Working/Issues/index.md @@ -7,6 +7,8 @@ description: How issues are formatted and organized across the MSX ecosystem. Guidance for how issues are formatted and organized across the MSX ecosystem. +Start with [Issue Planning](Process/Planning.md) to separate Epic/PBI consumer expectations from Task/Bug technical delivery plans, then follow the native type and process pages below. + | Section | Description | diff --git a/src/docs/Ways-of-Working/Readme-Driven-Context.md b/src/docs/Ways-of-Working/Readme-Driven-Context.md index bd15d676..e458d685 100644 --- a/src/docs/Ways-of-Working/Readme-Driven-Context.md +++ b/src/docs/Ways-of-Working/Readme-Driven-Context.md @@ -5,13 +5,13 @@ description: Why the README is the front door and the source of truth. # README-Driven Context -The README is the **evergreen context document** for every repository in the MSX ecosystem. It is the single source of truth for what a repository is, what it does, and how it works. Both humans and agents read the README before starting work — and update it whenever functionality changes. +The README is the **evergreen context document** for every repository in the MSX ecosystem. It is the single source of truth for what a repository is, what it does, and how it works. Both humans and agents read the README before starting work and keep it current when the delivered result affects its content. ## Core principles - **The README is the front door.** Anyone — human or agent — encountering the repository for the first time should understand the purpose, scope, and current capabilities from the README without reading source code. -- **The README is evergreen.** It is a living document that always reflects the current state of the repository. When functionality is added, changed, or removed, the README is updated in the same unit of work. -- **Documentation is not optional.** A feature that is not documented in the README is effectively invisible. Updating the README is part of completing the work, not a follow-up task. +- **The README is evergreen.** It is a living document that reflects the current state of the repository. Update affected content in the same unit of work. +- **Documentation is not optional.** A feature missing from the relevant README content is effectively invisible. Verification and any needed update are part of completing the work, not a follow-up task. - **The README is authoritative, but not automatically right.** It is the intended source of truth, yet a README can be wrong just as code can. When the README and the code disagree, [diagnose which is wrong](Principles/Engineering-Practices.md#intent-is-the-source-of-truth) — correct the README if the intent drifted, or fix the code if it diverged — so the two converge. ## What belongs in the README @@ -42,10 +42,12 @@ Detailed users and jobs belong in the [capability specification](Spec-Driven-Dev ## When to update the README -The README is updated **in the same pull request** that introduces the change. Documentation is part of the work — not a separate follow-up. +Verify the README **in the same pull request** that introduces the change and update affected content that would be missing or incorrect. The shared [documentation and design evidence](Definition-of-Ready-and-Done.md#documentation-and-design-evidence) gate owns verification, including evidence when the README already matches the delivered result. ### Update when +Review the relevant README content for these changes and update it where needed: + - A new feature, command, function, or capability is added. - An existing feature changes in behavior, parameters, or output. - A feature, command, or option is removed or deprecated. @@ -67,7 +69,7 @@ When a human or agent works on a repository, the README sequence is: 1. **Read the README first** — before reading source code, understand the project context. 2. **Use the README as a guide** — let documented scope and architecture inform where and how to make changes. -3. **Update the README as part of implementation** — same PR, not a follow-up. +3. **Verify the README as part of implementation** — update affected content and record completion evidence in the same PR, not a follow-up. 4. **Match the existing tone and structure** — heading levels, conventions, and style already present. 5. **Don't delete without reason** — if something is outdated, update it rather than removing it, unless the feature no longer exists. diff --git a/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md b/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md index dff9499c..c37cb2f1 100644 --- a/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md +++ b/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md @@ -9,6 +9,8 @@ One skeleton per artifact tier defined in [Spec-Driven Development](Spec-Driven- Each template assumes the [authoring conventions](Spec-Driven-Development.md#authoring-conventions): present tense, impersonal, normative, and free of dates and status. +These are durable artifact templates, not issue-body or implementation-plan templates. Issues follow their canonical [planning altitude](Issues/Process/Planning.md); delivered work verifies the resulting artifacts through the shared [documentation and design evidence](Definition-of-Ready-and-Done.md#documentation-and-design-evidence) gate. + ## Specification ````markdown diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Define.md b/src/docs/Ways-of-Working/Workflow-Stages/Define.md index 446e3ee1..382efe1e 100644 --- a/src/docs/Ways-of-Working/Workflow-Stages/Define.md +++ b/src/docs/Ways-of-Working/Workflow-Stages/Define.md @@ -36,13 +36,13 @@ Ground the issue so anyone reading it agrees on what "done" means, up to the [De ### 3. Plan -Decide how the work will happen and record the decisions. +Separate consumer expectations from delivery planning at the canonical [issue planning altitude](../Issues/Process/Planning.md). 1. Route the work through the [Issue Hierarchy](../Issues/Types/Hierarchy.md); do not infer altitude from effort, priority, or a legacy label. -2. For an Epic or PBI, establish native containment and dependency relationships and refine the first required children to their own readiness gates. -3. For a Task or Bug, produce one executable delivery plan sized for one pull request. Use the audited operational Task path only when no repository artifact exists. +2. For an Epic or PBI, apply the [consumer-expectation rule](../Issues/Process/Planning.md#consumer-expectations), establish native containment and dependency relationships, and refine the first required children to their own readiness gates. +3. For a Task or Bug, retain technical decisions and produce one test-first executable delivery plan sized for one pull request, including relevant design and documentation verification. Use the audited operational Task path only when no repository artifact exists. 4. Find the minimum viable path — spike, then proof of concept, then minimum viable product, then improve. -5. Record decisions at the issue's [planning altitude](../Issues/Process/Planning.md), with rationale and alternatives where they matter. +5. Keep durable technical choices in the design and per-change decisions in delivery leaves; link those artifacts from aggregates rather than prescribing their implementation. 6. Resolve open questions before finishing; defer anything that does not block this slice to a follow-up issue. ## Operating rules diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Implement.md b/src/docs/Ways-of-Working/Workflow-Stages/Implement.md index cb7ac6f0..c77a0b6a 100644 --- a/src/docs/Ways-of-Working/Workflow-Stages/Implement.md +++ b/src/docs/Ways-of-Working/Workflow-Stages/Implement.md @@ -35,13 +35,15 @@ Use [git worktrees](../Git-Worktrees.md) for every repository-delivery Task or B For each step in the delivery plan: -1. Implement the change and self-review the staged diff. +1. Define the failing test or repeatable verification before implementing the behavior, following the leaf's technical plan, then self-review the staged diff. 2. Commit per [Commit Conventions](../Commit-Conventions.md) — one logical change per commit. 3. Update the issue as each plan step completes — do not batch. 4. Push regularly so CI runs against current work. When the plan is wrong, stop and document the conflict in a comment, then update the plan before resuming. Out-of-scope problems go to [Define](Define.md). +Verify the leaf's relevant design and documentation against the delivered consumer behavior through the shared [completion evidence gate](../Definition-of-Ready-and-Done.md#documentation-and-design-evidence). Record the updated artifacts or justified already-correct links in the PR's supporting evidence; do not turn the parent Epic or PBI into a technical plan. + ### 4. Self-review and respond 1. Run the [Copilot review loop](../Contribution-Workflow.md#the-copilot-review-loop) until it reports a clean round. diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Review.md b/src/docs/Ways-of-Working/Workflow-Stages/Review.md index 1e28ee89..29b69fe5 100644 --- a/src/docs/Ways-of-Working/Workflow-Stages/Review.md +++ b/src/docs/Ways-of-Working/Workflow-Stages/Review.md @@ -41,6 +41,8 @@ Check each dimension per [Review Etiquette](../Review-Etiquette.md): - **Issue convergence sweep** — the pull request records the author's [sweep](Implement.md#6-issue-convergence-sweep), including scoped search coverage and any convergent issues linked with closing keywords. Spot-check at least one linked closing issue against the delivered diff; a claimed convergence with no visible delivery evidence is a blocking finding. - **Tests** — new behaviour has tests; bugs get regression tests. +For documentation and design, verify the shared [completion evidence gate](../Definition-of-Ready-and-Done.md#documentation-and-design-evidence): current artifacts, examples, links, and instructions, including justified no-change evidence where they already match the delivered behavior. + ### 4. Post the review Use severity prefixes per [Review Etiquette](../Review-Etiquette.md): `Blocking:`, `Question:`, `Suggestion:`, `Nit:`. Out-of-scope suggestions become new issues, not blocking comments. diff --git a/src/docs/Ways-of-Working/Workflow.md b/src/docs/Ways-of-Working/Workflow.md index bad46722..a60dee95 100644 --- a/src/docs/Ways-of-Working/Workflow.md +++ b/src/docs/Ways-of-Working/Workflow.md @@ -94,7 +94,7 @@ The goal is **shared understanding** — everyone (humans and agents) agrees on Turn the refined understanding into actionable work: - **Gap analysis** — diff the [evergreen specification](Documentation-Model.md#evergreen-and-evolutionary) for the affected capability against the current implementation. The gap is the work. -- **Route and decide** — assign the native type and add decisions at its [planning altitude](Issues/Process/Planning.md). +- **Route and define** — assign the native type and use its [planning altitude](Issues/Process/Planning.md): consumer expectations and scenarios in Epics/PBIs, technical decisions and test-first plans in Task/Bug leaves. - **Decompose aggregates** — use native sub-issues for Epic and PBI children, and native dependency edges only where execution is genuinely gated. - **Prepare delivery leaves** — refine Task and Bug children until they satisfy their type-specific readiness gate. @@ -108,7 +108,7 @@ Execute one ready, unblocked Task or Bug. For repository delivery: 1. **Branch** — create a branch (and [worktree](Git-Worktrees.md)) for the delivery leaf. 2. **Draft PR** — push early and open a draft pull request scoped to one Task or Bug delivery leaf. The pull request closes that scoped leaf; any additional convergent issues are linked separately through the session-end issue convergence sweep. This makes progress visible and attaches CI from the start. -3. **Implement** — work through the implementation plan. One logical change per commit. Update the issue as each plan step completes. +3. **Implement** — work through the leaf's test-first implementation plan, including relevant [documentation and design evidence](Definition-of-Ready-and-Done.md#documentation-and-design-evidence). One logical change per commit. Update the issue as each plan step completes. 4. **Test locally** — don't push known failures to CI. Push work as far inward as it can go. 5. **Self-review with automation** — run the [Copilot review loop](Contribution-Workflow.md#the-copilot-review-loop) until it reports a clean round, fixing in-scope feedback and filing follow-up issues for the rest. 6. **Standards and framework alignment pass** — once the change is complete, reconcile it against process, the applicable [Coding Standards](../Coding-Standards/index.md) chapters, and the repository's framework documentation, and record the result in the pull request. See [Implement](Workflow-Stages/Implement.md#5-standards-and-framework-alignment-pass). @@ -124,6 +124,7 @@ See [Commit Conventions](Commit-Conventions.md), [PR Format](PR-Format.md), [Con Every change gets a second perspective: - Does the PR deliver what its closing Task or Bug asks for? +- Does the delivered slice satisfy its applicable consumer scenarios, with current design, documentation, and working instructions? - Does it follow the project's standards and conventions? - Are there security concerns or undiscussed decisions? - Is the code clear and maintainable? @@ -141,7 +142,7 @@ publishes it, the description becomes part of the release record; otherwise it remains the durable change record. Write it for the identified readers, not only for reviewers. -Parent PBI and Epic issues close separately when their native children and aggregate acceptance criteria are complete. See [PR Format](PR-Format.md), [Issue Lifecycle](Issues/Process/Lifecycle.md), and [Branching and Merging](Branching-and-Merging.md#required-checks-and-auto-merge). +Parent PBI and Epic issues close separately when their native children, aggregate consumer scenarios, and [documentation and design evidence](Definition-of-Ready-and-Done.md#documentation-and-design-evidence) are complete. See [PR Format](PR-Format.md), [Issue Lifecycle](Issues/Process/Lifecycle.md), and [Branching and Merging](Branching-and-Merging.md#required-checks-and-auto-merge). ### Operate @@ -165,7 +166,7 @@ Planning happens at different time horizons and levels of detail: Detail increases as work moves from Later toward Now. - A single task lives in **Now / Detailed**. -- A PBI lives between **Now / Logical** and **Next / Detailed**. -- An Epic spans **Now → Next → Later** at **Conceptual / Logical** fidelity. +- A PBI's bounded consumer scenarios gain precision as it approaches **Now**; detailed implementation stays in its Task and Bug leaves. +- An Epic spans **Now → Next → Later** with strategic consumer outcomes at **Conceptual / Logical** fidelity, not technical implementation plans. This workflow follows the [Human–agent coexistence](Principles/AI-First-Development.md#human-agent-coexistence) principle — it is designed for humans first, with agents joining the same process rather than running a parallel one.