# Shape Spec

> 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.

- Skill: `leihuang23/shape-spec-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add leihuang23/shape-spec-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leihuang23/shape-spec-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: leihuang23 (https://skillmd.com/u/leihuang23)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leihuang23/shape-spec-2

---


# 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 `.workshop/specs/<slug>.md`:

```markdown
# <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.