Problem
While adopting 2119 for one composer attachment feature, an agent-generated first-pass spec decomposed the feature into 20+ enforced MUST requirements. Many of those requirements described implementation steps, UI details, or test-meta expectations rather than the core user workflows. (As an example: 21 requirement claims were generated for the attachment feature, which is a bit too much, esp. if you're going to have that scale for every feature in an app.)
That made the 2119 review process feel disproportionately heavy for a single feature: every small implementation detail became a separate coverage and fresh-context review obligation. After discussion, the more useful shape was a much smaller workflow-level spec: paste image, drag image, picker image, and the same three workflows for a representative non-image file type such as PDF, plus a few safety invariants around image payloads and file references.
2119 should help agents avoid this over-decomposition by default, especially when teams are beginning to add requirements for an existing app. Otherwise, the requirements list can become cumbersome quickly and discourage adoption.
Summary
When agents draft a first-pass feature spec, 2119 should encourage workflow-level requirements and warn against exploding a single feature into many implementation-step MUSTs.
In practice, an agent can over-decompose one feature into dozens of independently enforced requirements. That makes cover/review burdensome before the team has even decided which behaviors are core product promises versus implementation details, UI polish, or manual acceptance criteria.
Suggested docs / template guidance
Add guidance along these lines to the README, spec template, generated AGENTS instructions, or wherever 2119 teaches agents how to draft specs:
## Requirement granularity guidance
When drafting requirements for a feature, prefer a small number of user-meaningful,
workflow-level requirements over many implementation-step requirements.
A first-pass feature spec SHOULD usually contain about 3–8 enforced `MUST`
requirements. More granular requirements are appropriate only when each one represents
a distinct user promise, safety invariant, compatibility guarantee, or independently
valuable behavior.
Avoid turning every implementation detail into a separate `MUST`. Instead:
- Use `[manual]` for behavior that is primarily verified through UI/manual inspection.
- Use `SHOULD` for polish, edge cases, and preferred behavior that should not block the
first enforcement pass.
- Use explanatory notes or acceptance-checklist bullets for implementation details.
- Split requirements only when the resulting requirement has a clear independent test
or review value.
Good:
> A user MUST be able to paste an image into the composer, see it appear as an
> attachment chip, and send it as an image attachment.
Less good as separate first-pass requirements:
> The paste handler MUST read from the macOS pasteboard.
> The classifier MUST create an image attachment.
> The chip area MUST become visible.
> The chip MUST show a thumbnail.
> The RPC payload MUST contain an image object.
> The transcript MUST show the image.
Those details may be useful, but they are often better expressed as notes,
manual criteria, or later hardening requirements unless each one needs independent
enforcement.
Spec sizing smells
It would also help to document warning signs such as:
### Spec sizing smells
Reconsider the spec if:
- One feature produces more than ~10 enforced `MUST`s before tests exist.
- Most requirements are restating internal implementation steps.
- A reviewer would need to approve many requirements using the same single test.
- The requirement says “MUST cover” or “MUST test” instead of describing product behavior.
- Many requirements differ only by small UI details.
Template suggestion
A default feature-spec structure could nudge agents toward:
## Requirements
### Core workflows
List 3–5 user workflows as `MUST`s.
### Safety / compatibility invariants
List only critical invariants as `MUST`s.
### Manual acceptance criteria
Use `[manual]` for visual/UI workflows that are not automated yet.
### Notes / non-goals
Put implementation details and deferred polish here instead of making them enforced
requirements.
Why
This keeps 2119 adoption lightweight for existing projects. Teams can start with a manageable enforced surface, then split or harden requirements later when individual behaviors prove important enough to test/review independently.
Problem
While adopting 2119 for one composer attachment feature, an agent-generated first-pass spec decomposed the feature into 20+ enforced
MUSTrequirements. Many of those requirements described implementation steps, UI details, or test-meta expectations rather than the core user workflows. (As an example: 21 requirement claims were generated for the attachment feature, which is a bit too much, esp. if you're going to have that scale for every feature in an app.)That made the 2119 review process feel disproportionately heavy for a single feature: every small implementation detail became a separate coverage and fresh-context review obligation. After discussion, the more useful shape was a much smaller workflow-level spec: paste image, drag image, picker image, and the same three workflows for a representative non-image file type such as PDF, plus a few safety invariants around image payloads and file references.
2119 should help agents avoid this over-decomposition by default, especially when teams are beginning to add requirements for an existing app. Otherwise, the requirements list can become cumbersome quickly and discourage adoption.
Summary
When agents draft a first-pass feature spec, 2119 should encourage workflow-level requirements and warn against exploding a single feature into many implementation-step
MUSTs.In practice, an agent can over-decompose one feature into dozens of independently enforced requirements. That makes
cover/reviewburdensome before the team has even decided which behaviors are core product promises versus implementation details, UI polish, or manual acceptance criteria.Suggested docs / template guidance
Add guidance along these lines to the README, spec template, generated AGENTS instructions, or wherever 2119 teaches agents how to draft specs:
Spec sizing smells
It would also help to document warning signs such as:
Template suggestion
A default feature-spec structure could nudge agents toward:
Why
This keeps 2119 adoption lightweight for existing projects. Teams can start with a manageable enforced surface, then split or harden requirements later when individual behaviors prove important enough to test/review independently.