datashaman/skills/specify

name: specify

description: Turn a GitHub issue, ticket, or chat into scope, testable acceptance criteria, and concrete API/data/UI contracts for spec.json. Stop and consult the human stakeholder whenever anything is ambiguous or the source material is broken—never guess. Use before any implementation.

Specify

When to use

• Spec Agent (or anyone) must produce spec.json from messy input.
• You need a single source of truth for what “done” means before code changes.

Consult the stakeholder (do not skip)

Any ambiguity, conflict, or problem with the source—and you must involve the human who owns the request (issue author, PM, product owner, or whoever filed the ticket)—before you treat the spec as final.

Stop and ask when, for example:

• Requirements are vague, contradictory, or could be read multiple ways.
• Scope, priority, or “MVP vs later” is unclear.
• Auth, data, compliance, or security expectations are missing or assumed.
• The issue/ticket is empty, in the wrong place, duplicated, or missing context you need.
• Picking an option would materially change behavior, cost, or risk and nobody has chosen.

Record what you asked and what they decided (in the ticket thread, open_questions, or spec notes). Do not invent answers to fill gaps so implementation can start sooner.

Inputs (gather explicitly)

• Primary request (issue body, ticket, Slack/Chat thread).
• Stack hints: package.json, composer.json, pyproject.toml, or README “Tech stack” section.
• Auth model: how users are identified (session cookie, JWT header, SSO). If unknown, record as an open question.

Steps (do in order)

1. Stakeholder & job-to-be-done — One paragraph: who acts and what outcome they need.
2. Requirements list — Bullet list labeled functional vs non-functional (latency, accessibility, offline, etc.).
3. Scope table — Two columns: In MVP | Out of MVP with explicit “won’t do” items (prevents scope creep).
4. Acceptance criteria — For each requirement, one row:

• ID (e.g. AC-3)
• Given / When / Then (observable; avoid “should be fast”; use numbers where possible).
• Negative case (validation error, permission denied, empty state).

5. Contracts (fill spec.json contracts)

• API: HTTP method + path, request/response JSON shape, status codes for success and errors (e.g. 400 validation, 401/403 auth, 409 conflict).
• Data: entity names, fields, unknown → open_questions in spec, not guessed columns.
• UI states: loading / success / error / empty (what the user sees).

6. Assumptions & open questions — Anything that would change API or security if answered differently. If anything material is still open after this pass, consult the stakeholder; do not ship a spec.json that pretends those decisions are made.

Output

• Valid spec.json (see schemas/spec.schema.json and examples/spec.example.json).
• Optional: paste a summary back to the GitHub issue with link to runs/issue-<n>/spec.json if you use issue-linked runs.

Anti-patterns

• Guessing or silently resolving ambiguity instead of consulting the stakeholder.
• Vague AC (“user can use feature”) without Given/When/Then.
• Missing error behavior and HTTP semantics for web APIs.
• Implementing before Out of MVP is written.