Two more principles: build what the work demanded, and extend the core

Status: shipped. vocion-core#359 is merged to main (1d496452) and is in v2.82.0. It changes two files: docs/MANIFESTO.md and CLAUDE.md. Part of the 2026-09-16 release notes.

The Product Design Manifesto shipped yesterday with seventeen principles and a twelve-question test. It is the document a change is judged against before it ships, and the one a coding agent working in the tree is pointed at before it proposes any product surface. Two principles were missing. They are the two that most often decide whether a day of building was worth anything, and they are now §18 and §19.

§18 — Implementation is the forcing function

Roadmaps drift toward what sounds important. Building something real tells the truth.

The claim is that a feature earns its place by being needed to finish actual work — a deployment, a client outcome, a dogfood use case — not by being proposed. Use the product, find where it fails, close that gap. The backlog should read as a record of what implementation demanded, not a wish list written in advance.

Four tests come with it:

• Prefer the gap you hit today over the gap you predict for next quarter.
• A capability nobody hit a wall without is speculation.
• Feedback from real use becomes work, not just a reply.
• If a feature cannot name the thing it unblocked, it is not ready to build.

The last one is the sharp edge. It is a question any change can be asked in a review, and most speculative work cannot answer it. The principle closes on the reason Vocion runs inside its own company before anyone else's: if we did not need it to finish something, we do not need it yet.

This one is not theoretical for this release. The Slack work in the same release exists because three specific gaps were hit replying to a release announcement in a thread, and the agent answered "No page context here — I can't tell what 'this' refers to." Nobody had that on a roadmap. The work that shipped can name the thing it unblocked.

§19 — Extend the core. Keep the specifics at the edge.

Two questions before any new surface: How can we simplify this? How can we make this universal?

Every screen, component and interaction pattern should be one of a small number of shapes, used everywhere. When a need does not fit one of them, the answer is almost always to extend the shape rather than build a second one beside it — and the principle says that holds especially when the gap is legitimate:

A real gap closed generically makes the whole platform better. The same gap closed locally makes one screen better and the platform worse.

That is the sentence that does the work. The usual instinct is the opposite: a real gap feels like the licence to build something bespoke, because the need is genuine. §19 says a genuine need is the strongest argument for fixing the shared thing, not for going around it. Its tests:

• Extend a core component before adding a custom one.
• Extend an interaction pattern before inventing a second way to do the same job.
• Two surfaces doing the same job is a defect, not a choice.
• A one-off is a core gap someone decided not to fix.

The counterweight: concretions belong in templates

A principle that only says generalise is a licence to put everything in the platform, which is its own failure. So §19 carries an explicit counterweight. Universal does not mean everything belongs in the core. Anything true only for one industry, one customer, or one vertical workflow is a concretion, and concretions do not belong in the platform. They belong in templates, workspaces and the marketplace, where they can be specific, opinionated and disposable without taxing everyone else.

• The core holds the general capability. A template holds the specific application of it.
• If it names an industry, a customer, or a single workflow, it is not core.
• Every vertical added to the core is paid for by every workspace that will never use it.

The two halves resolve into one line: generalize into the core, specialize at the edge. A recruiting workflow is not a Vocion feature; the extraction, review and autonomy primitives it is built from are. The recruiting workflow is a template.

The test is now fifteen questions

The pre-ship test grew by three, and two of the new ones sit near the top — before does the user know what to do next, because they decide whether a thing should exist at all:

What changed for a builder

CLAUDE.md — the file every coding agent working in the repo reads first — now restates both rules directly rather than only linking the manifesto, because the two are the ones that bind day-to-day engineering decisions. An agent proposing a new component in this tree is now reading "extend an existing component or interaction pattern rather than building a second one beside it" before it writes the file.

Changes to the manifesto are product decisions. Propose them as a pull request and say which principle you are changing and why.

Where this lives in the repo

• The document: docs/MANIFESTO.md, §18 and §19, and "The test"
• The restatement builders and agents read: CLAUDE.md
• PR: #359, commit 1d496452
• The first seventeen: The Product Design Manifesto is in the repo, and it is the bar