Skip to content

📖 [Docs]: Add a Specify-the-minimum (Lean) principle and Non-goals to the spec standard#35

Merged
Marius Storhaug (MariusStorhaug) merged 1 commit into
mainfrom
docs/spec-minimalism-and-non-goals
Jul 12, 2026
Merged

📖 [Docs]: Add a Specify-the-minimum (Lean) principle and Non-goals to the spec standard#35
Marius Storhaug (MariusStorhaug) merged 1 commit into
mainfrom
docs/spec-minimalism-and-non-goals

Conversation

@MariusStorhaug

Copy link
Copy Markdown
Member

The spec standard now names an explicit minimalism principle and gives every spec a place to state its non-goals — two structural lessons borrowed from how Google's Open Knowledge Format is written. This mirrors the same change made to the AI-Platform copy of the standard, keeping the two in sync.

New: A "Specify the minimum" principle

The standard gains a short Specify the minimum section: 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, because over-specification is waste. It grounds the idea in the existing Lean Software Development principle and points at the altitude test as how it is applied.

New: A Non-goals element

Both the standard's "a spec contains" list and the inline specification template gain Non-goals — the outcomes a capability deliberately does not pursue, named so its intent is not misread. It sits beside Scope but is distinct: out of scope bounds this change; non-goals bound the intent.

A third idea considered from OKF — a dedicated worked-example section — was deliberately skipped: the Given/When/Then acceptance criteria already carry that weight for a feature spec, and OKF's heavier interoperability machinery (conformance, producer/consumer obligations, artifact versioning) belongs only to specs that define a contract.

Technical Details

  • src/docs/Ways-of-Working/Spec-Driven-Development.md — new ## Specify the minimum section; a Non-goals bullet in the "A spec contains" list; a ## Non-goals heading in the inline specification template.
  • Index check, link validation, and markdownlint all pass locally.
  • Companion change: the AI-Platform mirror of this standard receives the same update.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the “Spec-Driven Development” standard to make minimalism explicit (“Specify the minimum”) and to add a dedicated place for stating Non-goals, aligning the spec standard’s structure with lessons borrowed from Google’s Open Knowledge Format and keeping it in sync with the AI-Platform mirror described in the PR.

Changes:

  • Adds a new ## Specify the minimum principle section describing how to keep specs intentionally minimal and implementation-agnostic.
  • Adds Non-goals to the “A spec contains” checklist to distinguish intent-boundaries from “Out of scope” change-boundaries.
  • Extends the inline specification template with a ## Non-goals section.

@MariusStorhaug
Marius Storhaug (MariusStorhaug) merged commit 930550f into main Jul 12, 2026
20 checks passed
@MariusStorhaug
Marius Storhaug (MariusStorhaug) deleted the docs/spec-minimalism-and-non-goals branch July 12, 2026 14:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants