diff --git a/src/docs/Ways-of-Working/Documentation-Model.md b/src/docs/Ways-of-Working/Documentation-Model.md index 1323268..7c56283 100644 --- a/src/docs/Ways-of-Working/Documentation-Model.md +++ b/src/docs/Ways-of-Working/Documentation-Model.md @@ -189,6 +189,23 @@ Current product guidance does not establish older-version behavior. Decision records preserve choices, rationale, and supersession links. Research preserves point-in-time findings. Evergreen resource docs do not replace these records. +## Subject-focused content + +The body describes the subject, not the document. Start with the rule, procedure, +behavior, or design that the reader needs. Remove self-description such as +"This document explains..." and authoring notes that do not describe the subject. + +Keep document-maintenance metadata out of the body: bylines, document owners, +approval status, review dates, document versions, and revision history. +Keep required navigation front matter, including `title` and `description`. +The team that owns the subject owns its documentation. `CODEOWNERS` records that +ownership. Git history, pull requests, and issues retain change and review records. + +Preserve the subject's scope, requirements, source links, mechanisms, alternatives, +and rationale. Designs explain how the system works and why the chosen approach +meets its requirements. Keep operational ownership, product versions, observation +dates, and decision status when they are facts needed to understand or use the subject. + ## Concise by default Concise documentation reduces the effort needed to find an answer, for humans diff --git a/src/docs/Ways-of-Working/Evolutionary-Development.md b/src/docs/Ways-of-Working/Evolutionary-Development.md index 52991c6..efaf924 100644 --- a/src/docs/Ways-of-Working/Evolutionary-Development.md +++ b/src/docs/Ways-of-Working/Evolutionary-Development.md @@ -11,7 +11,7 @@ The method uses Darwin's theory of evolution as an analogy: variation, selection The method uses small experiments and frequent feedback to compare alternatives. -This standard connects three practices in one feedback cycle. [Spec-Driven Development](Spec-Driven-Development.md) records intent in a spec for the why and what, and a design for the how. Behavior-driven discovery expresses that intent as Given / When / Then acceptance criteria. Test-driven development implements the criteria and unit tests in small steps. +The feedback cycle connects three practices. [Spec-Driven Development](Spec-Driven-Development.md) records intent in a spec for the why and what, and a design for the how. Behavior-driven discovery expresses that intent as Given / When / Then acceptance criteria. Test-driven development implements the criteria and unit tests in small steps. Context, criteria, and feedback guide the cycle, whether a person, an agent, or a group of agents drives it (see [How the loop is driven](#how-the-loop-is-driven)). It builds on [engineering practices](Principles/Engineering-Practices.md) (test-first where it pays, small batches, reversible decisions) and [AI-first development](Principles/AI-First-Development.md). @@ -118,12 +118,14 @@ This makes [context-first development](Principles/AI-First-Development.md#contex ## The instructions evolve too +Durable, reusable instructions follow the same engineering practices as code. This includes standards, guides, stored prompts, skills, and agent files. Source control, testing and verification, pull requests, review, and acceptance apply through the [Contribution Workflow](Contribution-Workflow.md). One-off chat requests are outside these source-control and pull-request requirements. + > [!IMPORTANT] -> Self-directed update is a standing directive, not an optional courtesy. A person or agent that learns something or finds an incorrect instruction is expected to improve that instruction immediately. Do not leave the correction for someone else. The next cycle uses that correction. A cycle that cannot improve its instructions cannot evolve. +> Self-directed update is a standing directive, not an optional courtesy. A person or agent that learns something or finds an incorrect instruction starts a proposed correction immediately. Do not leave the correction for someone else. Starting a correction does not bypass verification, review, or acceptance. The next cycle uses the accepted correction. A cycle that cannot improve its instructions cannot evolve. -Standards, guides, and agent instructions provide context for each cycle (see [How the loop is driven](#how-the-loop-is-driven)). A weak instruction can misdirect every reader. Correct instructions when they are wrong and refine them when evidence identifies a better approach. This maintenance is part of the work. It applies [self-improving agents](Principles/AI-First-Development.md#self-improving-agents) to the instructions themselves. +These instructions provide context for each cycle (see [How the loop is driven](#how-the-loop-is-driven)). A weak instruction can misdirect every reader. Correct instructions when they are wrong and refine them when evidence identifies a better approach. This maintenance is part of the work. It applies [self-improving agents](Principles/AI-First-Development.md#self-improving-agents) to the instructions themselves. -When a cycle exposes an incorrect instruction or a better way of working, propose the correction as its own small change. Review and merge it through the same [decision point](Principles/AI-First-Development.md#decision-before-change). Relevant signals include: +When a cycle exposes an incorrect instruction or a better way of working, propose the correction as its own small change. Its pull request must be reviewed, approved, and merged through the same [decision point](Principles/AI-First-Development.md#decision-before-change). Only then does the correction become accepted guidance. Relevant signals include: - An agent needs the same clarification twice, or a `[NEEDS CLARIFICATION]` marker keeps recurring. - A review comment teaches a rule that is not written down yet. @@ -131,7 +133,7 @@ When a cycle exposes an incorrect instruction or a better way of working, propos - A turn goes wrong in a way a clearer instruction would have prevented. - A cycle finds a better prompt, sequence, or rule that should be reused. -A standard is defined once and referenced by its consumers ([Agentic Development](../Capabilities/agentic-development/index.md)). Readers receive corrections through that shared source. The same verification that keeps a spec aligned with intent also keeps instructions accurate as understanding grows. +A standard is defined once and referenced by its consumers ([Agentic Development](../Capabilities/agentic-development/index.md)). Correct a missing or incorrect rule in its canonical document before adding or updating instructions that depend on it. Prompts, skills, and agent instructions link to that document instead of copying the rule. The same verification that keeps a spec aligned with intent also keeps instructions accurate as understanding grows. ## Working a v1 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 727b45e..ec4d417 100644 --- a/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md +++ b/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md @@ -7,7 +7,9 @@ description: A copyable skeleton for every spec-driven artifact — specificatio Each artifact tier defined in [Spec-Driven Development](Spec-Driven-Development.md#the-artifact-tiers) has a template. Copy the template for the artifact. Each template contains all standard sections. **Delete a heading rather than marking it "N/A"** when it does not apply. Empty sections make relevant content harder to find. -Apply the [authoring conventions](Spec-Driven-Development.md#authoring-conventions) for the artifact being written. Specifications and designs use present-tense, impersonal, normative prose without dates or delivery status. Guides and playbooks use direct imperative steps. Research records past findings. Decision records preserve the rationale for the original choice. +Apply the [authoring conventions](Spec-Driven-Development.md#authoring-conventions) for the artifact being written. Specifications and designs use present-tense, impersonal, normative prose without document-maintenance dates or delivery status. Guides and playbooks use direct imperative steps. Research records past findings. Decision records preserve the rationale for the original choice. + +Use the [subject-focused content rule](Documentation-Model.md#subject-focused-content) when you replace the placeholders. 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. @@ -166,7 +168,7 @@ description: # — Design - + ## Specification @@ -219,7 +221,7 @@ description: # — Implementation - + ## Design @@ -281,12 +283,12 @@ description: ````markdown --- title: -description: +description: --- # - + | | | | | |---|---|---|---| @@ -295,7 +297,7 @@ description: ## Research -Research is the one artifact written in the past tense. Git records its dates. +Research is the one artifact written in the past tense. Git records its document dates. ````markdown --- @@ -407,11 +409,11 @@ description: # - + ## Purpose and scope - + **Out of scope** @@ -464,8 +466,7 @@ description: # — Decisions - + ## Recorded decisions diff --git a/src/docs/Ways-of-Working/Spec-Driven-Development.md b/src/docs/Ways-of-Working/Spec-Driven-Development.md index 11e9ce1..5f15177 100644 --- a/src/docs/Ways-of-Working/Spec-Driven-Development.md +++ b/src/docs/Ways-of-Working/Spec-Driven-Development.md @@ -7,7 +7,7 @@ description: Requirements, artifact roles, and the path from a need to a deliver The specification is the source of truth for *why* a change matters and *what* it must do. Design, delivery issues, code, and tests serve that specification. When intent changes, the spec changes first. -This standard defines the **specification**, its **design**, and the supporting artifact tiers. It states their content, level of detail, and role in the delivery lifecycle. It builds on the [evergreen documentation](Principles/Engineering-Practices.md#evergreen-documentation) principle for authoring and the [engineering practices](Principles/Engineering-Practices.md) for planning, delivery, and measurement. +Specifications, designs, and supporting artifacts use [evergreen documentation](Principles/Engineering-Practices.md#evergreen-documentation) for authoring and [engineering practices](Principles/Engineering-Practices.md) for planning, delivery, and measurement. ## The model @@ -242,8 +242,7 @@ Separating the spec from the design keeps requirements stable across refactors w - **Write intended state.** Use present-tense, definitive prose and state each fact once, as with all [evergreen documentation](Principles/Engineering-Practices.md#evergreen-documentation). Keep task lists, status, and history in issues and PRs, not the spec. - **Write impersonally.** Use third person throughout. A spec does not address the reader, name a person, or refer to "we" or "the team". It states facts that remain valid when roles or teams change. - **State enduring problems, not timing.** Avoid "why now", "currently", "recently", and similar time-bound framing. State the condition that makes the capability valuable. Record a durable time bound, such as a published deprecation or contractual date, as a constraint. -- **Let git carry the record.** Keep created and updated dates, revision numbers, authorship, and changelogs in repository history, not document fields. Commits and pull requests that reference the spec preserve that history without duplicate records. -- **Ownership is by location, not a byline.** The team that owns the code owns its spec ([docs live close to the code](../Coding-Standards/Documentation.md#the-hierarchy-of-documentation)). Accountability lives in `CODEOWNERS`, not a per-document owner field that can become incorrect. +- **Keep the body focused on its subject.** Follow the [Documentation Model](Documentation-Model.md#subject-focused-content). - **Conform, do not restate.** A spec links up to the principle or standard it obeys and never copies it. The direction is one-way by [design](Principles/index.md#principles-do-not-link-down): principles do not link down to specs. - **Mark unknowns, do not guess.** If the need is unclear, add an explicit `[NEEDS CLARIFICATION: the specific question]` marker. Do not invent an answer. Resolve and remove all markers before acceptance. - **Self-review against a checklist.** Before review, confirm that no clarification markers remain. Confirm that every requirement is testable and has at least one scenario. Confirm that success criteria are measurable.