Shape Spec

Shape Spec

Turn ambiguity into testable behavior without forcing the user to answer facts the repository can reveal.

Workflow

1. Inspect the repository, issue, relevant behavior, conventions, data model, and constraints.
2. Restate the user problem as an observable outcome, not a feature label.
3. Maintain an ambiguity ledger with fact, inference, product choice, and unknown entries.
4. 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.
5. Write acceptance examples before proposing implementation.
6. Identify non-goals, invariants, failure behavior, permissions, migration, accessibility, observability, and rollback needs.
7. Define evidence that would prove each acceptance example.
8. Run the readiness gate.

Specification template

Write 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

Persistence gate

Create specs/<slug>.md and specs/<slug>.evidence.md as real workspace files. Use a visible specs/ directory for consistent behavior across Codex, Kimi Code, and Grok Build. Write the specification skeleton before filling sections, then re-read both files from disk before reporting completion. Only claim a path was persisted or a check passed when the re-read proves it.

If workspace writes are unavailable, return the specification in the response and state that persistence was unavailable. Never invent file creation, file contents, commands, or verification output.

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

Persist specs/<slug>.evidence.md with the spec path, key decisions, facts discovered, questions answered, readiness result, checks actually performed, and remaining risks. Never claim user approval unless it was actually given.