Spec guidance tells agents what to avoid, not how to keep a spec small and readable #2139

Problem

Agents writing OpenSpec specs get format rules and a list of what to leave out. They get no picture of what a good spec looks like, and nothing says keeping it readable is their job. So each new behavior lands as another clause on the nearest requirement, and requirements keep growing until nobody reads them.

Who this affects

Anyone whose specs are mostly written and kept up by agents, especially long-lived projects. Every MODIFIED delta has to copy the whole requirement, so a grown requirement makes every later change to it large too.

What we've seen

In one of our own projects (about 800 requirements, all written by agents over a month):

• 81% of the main spec's requirements have more than one SHALL. The longest has 19 SHALLs, and one runs to 791 words.
• New requirements start out this way; they don't only grow into it. The share of newly added requirements with more than one SHALL went from 57% in late September to 90% in mid-October, and the average went from 1.8 to 5.0 SHALLs. The model was the same throughout. Agents copy the shape of the specs around them, so each long requirement makes the next one look normal.
• A 10-word edit to one requirement produced a 180-word MODIFIED block.

Why today's guidance doesn't prevent it

• The specs instruction covers what a spec is (a behavior contract), what to avoid, and the format (### Requirement: <name> followed by a description). It never says what a requirement is as a unit, who reads it, or how a spec as a whole should read.
• docs/writing-specs.md has the right idea ("A good requirement is one behavior, stated so plainly you could hand it to someone else to test"), but agents never receive that doc.
• Agents can only get the guidance through openspec instructions specs --change <name>. An agent editing openspec/specs/ directly, or editing a delta after it was written, gets none of it.
• The fix so far has been rules: a 500-character limit, plus exceptions for when to split and when not to (feat(validation): make requirement-description limits configurable by lifecycle scope #2069 asks to make the limit configurable). Each edge case adds another rule, and none of them tells the agent what it's aiming for.

What we have in mind (open for discussion)

Positive guidance that makes the agent the spec's keeper:

• What a requirement is: one promise someone relies on, named after that promise, in a sentence or two. Its cases, failures included, are its scenarios.
• Who reads it: a reviewer deciding yes or no, a test that names a scenario, the next agent changing it. So each requirement should stand on its own and be changeable on its own.
• The spec as an outline: read top to bottom, the requirement headers should list what the capability promises.
• Where new behavior goes: ask whether it's a new promise or a change to an existing one.
• Leave it easier to read than you found it: that includes splitting a multi-promise requirement you're already editing.
• Reachable on every edit: an agent should get this whenever it edits a spec, not only when it creates a change's specs artifact.

We're trying a version of this as a project rule and will report back on what changes.

Open questions:

1. Should this live in the schema's specs instruction, in a shared spec-writing instruction any workflow can load, or both?
2. Should splitting a requirement you're editing be the default? Today the guidance says to split only when the user asks.

Related: #2069, #829.