From bc08b1457bd72a513d9f97ce3c93df0232861beb Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 11 Jul 2026 22:20:23 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20[Docs]:=20Add=20a=20Specify-the-?= =?UTF-8?q?minimum=20(Lean)=20principle=20and=20Non-goals=20to=20the=20spe?= =?UTF-8?q?c=20standard?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/docs/Ways-of-Working/Spec-Driven-Development.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/docs/Ways-of-Working/Spec-Driven-Development.md b/src/docs/Ways-of-Working/Spec-Driven-Development.md index 24134d0..663ae39 100644 --- a/src/docs/Ways-of-Working/Spec-Driven-Development.md +++ b/src/docs/Ways-of-Working/Spec-Driven-Development.md @@ -42,6 +42,7 @@ A spec **contains**: - **Outcomes and impact** — the result in the world, and its expected effect on delivery (see [Impact](#impact)). - **Users and jobs** — who uses this and the job it gets done. - **Scope** — what is included, and an explicit list of what is out of scope. +- **Non-goals** — outcomes it deliberately does not pursue, named so its intent is not misread; distinct from out of scope, which bounds this change. - **Requirements** — what the capability does and the qualities it must hold, functional and non-functional (see [Requirements](#requirements)). - **Acceptance criteria** — observable behavior that verifies the requirements (see [Acceptance criteria](#acceptance-criteria)). - **Constraints, assumptions, and dependencies** — the boundaries it respects and the work, access, or decisions it waits on. @@ -57,6 +58,12 @@ A spec **excludes** — this is the design's job: The altitude test: push detail *down* into the design, and push scope *up* into the epic. If a sentence would change when the team picks a different library, it belongs in the design, not the spec. This is the same rule the [Issue Format](Issue-Format.md) applies to issues — describe the *what* and *why*, never the *how*. +## Specify the minimum + +A spec fixes the smallest set of requirements that make the capability correct and verifiable, and leaves every other choice to the design and the people building it. Over-specification is waste: it commits the team to decisions before they must be made, and every detail the spec pins is one more thing that rots when the implementation moves. Fix what must be agreed; leave the rest open. + +This is [Lean Software Development](Principles/Planning-and-Delivery.md#lean-software-development) and YAGNI applied to intent — the fewer things a spec pins, the longer it stays true and the more freedom the people building it keep. The altitude test above is how the principle is applied in practice. + ## Requirements Requirements are testable statements of what must be true — never how it is built. Write them with the [BCP 14](https://www.rfc-editor.org/info/bcp14) keywords — **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, **MAY**, and the rest of the set — in uppercase, where they carry their normative meaning ([RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174)). @@ -164,6 +171,10 @@ Copy these skeletons to start a `spec.md` and its `design.md`. Every section is - <...> +## Non-goals + +- + ## Functional requirements ### FR1 — { #fr1 }