Shape Spec
Turn ambiguity into testable behavior without forcing the user to answer facts the repository can reveal.
Workflow
- Inspect the repository, issue, relevant behavior, conventions, data model, and constraints.
- Restate the user problem as an observable outcome, not a feature label.
- Maintain an ambiguity ledger with
fact, inference, product choice, and unknown entries.
- Resolve facts and safe inferences through inspection. Ask one question at a time only for material product choices. In a non-interactive run, ask only the single highest-leverage question now; record dependent ambiguities without presenting them as additional questions.
- Write acceptance examples before proposing implementation.
- Identify non-goals, invariants, failure behavior, permissions, migration, accessibility, observability, and rollback needs.
- Define evidence that would prove each acceptance example.
- Run the readiness gate.
Specification template
Write .workshop/specs/<slug>.md:
# <outcome>
Status: draft | ready | blocked
## User problem and observable outcome
## Context discovered
## Scope
### In
### Out
## Acceptance examples
### Example 1: <name>
Given ...
When ...
Then ...
## Invariants and failure behavior
## Interfaces and data
## Accessibility, security, privacy, and observability
## Migration and rollback
## Verification plan
| Acceptance example | Evidence | Layer | Command or procedure |
| --- | --- | --- | --- |
## Decision and ambiguity ledger
## Limits
Use MUST, SHOULD, and MAY only when their strength is intentional. Avoid vague words such as fast, intuitive, robust, seamless, and support unless paired with observable criteria.
Readiness gate
A spec is ready only when:
- every in-scope behavior has at least one acceptance example;
- failure and empty states are explicit where relevant;
- non-goals prevent obvious scope creep;
- interface and data changes are named;
- material product choices are resolved;
- each acceptance example has a feasible verification path;
- remaining unknowns do not change the requested outcome.
When the gate is blocked, add ## Decision requested now with exactly one question, its concrete options, and the behavioral consequence of each. Do not convert an engineering preference into a MUST-level requirement merely to make the spec look ready.
Evidence packet
Return the spec path, key decisions, facts discovered, questions answered, readiness result, and remaining risks. Never claim user approval unless it was actually given.
1---2name: shape-spec-23description: Convert a rough feature idea, product request, or behavioral change into an implementable specification with examples, non-goals, invariants, interfaces, risks, and a verification plan. Use before planning or coding when the outcome is ambiguous. Do not use when an approved spec already answers these questions.4license: Apache-2.05---67# Shape Spec89Turn ambiguity into testable behavior without forcing the user to answer facts the repository can reveal.1011## Workflow12131. Inspect the repository, issue, relevant behavior, conventions, data model, and constraints.142. Restate the user problem as an observable outcome, not a feature label.153. Maintain an ambiguity ledger with `fact`, `inference`, `product choice`, and `unknown` entries.164. Resolve facts and safe inferences through inspection. Ask one question at a time only for material product choices. In a non-interactive run, ask only the single highest-leverage question now; record dependent ambiguities without presenting them as additional questions.175. Write acceptance examples before proposing implementation.186. Identify non-goals, invariants, failure behavior, permissions, migration, accessibility, observability, and rollback needs.197. Define evidence that would prove each acceptance example.208. Run the readiness gate.2122## Specification template2324Write `.workshop/specs/<slug>.md`:2526```markdown27# <outcome>28Status: draft | ready | blocked2930## User problem and observable outcome31## Context discovered32## Scope33### In34### Out35## Acceptance examples36### Example 1: <name>37Given ...38When ...39Then ...40## Invariants and failure behavior41## Interfaces and data42## Accessibility, security, privacy, and observability43## Migration and rollback44## Verification plan45| Acceptance example | Evidence | Layer | Command or procedure |46| --- | --- | --- | --- |47## Decision and ambiguity ledger48## Limits49```5051Use MUST, SHOULD, and MAY only when their strength is intentional. Avoid vague words such as fast, intuitive, robust, seamless, and support unless paired with observable criteria.5253## Readiness gate5455A spec is `ready` only when:5657- every in-scope behavior has at least one acceptance example;58- failure and empty states are explicit where relevant;59- non-goals prevent obvious scope creep;60- interface and data changes are named;61- material product choices are resolved;62- each acceptance example has a feasible verification path;63- remaining unknowns do not change the requested outcome.6465When the gate is blocked, add `## Decision requested now` with exactly one question, its concrete options, and the behavioral consequence of each. Do not convert an engineering preference into a MUST-level requirement merely to make the spec look ready.6667## Evidence packet6869Return the spec path, key decisions, facts discovered, questions answered, readiness result, and remaining risks. Never claim user approval unless it was actually given.
leihuang23