to-spec · git:20261118.581e4cd · 2026-11-18 · sha256 16c238f670cddc1e

to-spec git:20261118.581e4cdA

Immutable. This exact content never changes and is served at /api/v1/blob/16c238f670cddc1e.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_sfxxnz3zj4ymreed/16c238f670cddc1ef8d4184851095298269c8c79e28b60ce604749ed4dcb7ef4.json

Then /plugin install to-spec@markdownregistry-sfxxnz3zj4ymreed in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: to-spec
description: Audits a Discovery Decision Record or PRD and expands it into an industrial-grade, repo-grounded specification (specs/<slug>.md) with configurability, logging, security, performance, reusable assets, and requirement-to-test traceability. Use before slicing multi-session tickets.
---

# To Spec (Industrial-Grade Grounded Specification)

Convert a confirmed Discovery Decision Record (`docs/discovery/<slug>.md`) or PRD into an unambiguous specification at `specs/<feature-slug>.md` using [resources/spec-template.md](resources/spec-template.md).

## Decision tree

1. **Does a confirmed DDR (`docs/discovery/<slug>.md`) or explicit PRD exist?**
   - **No** → Stop and run `/discover` (or built-in `/grill-me`) first.
   - **Yes** → Proceed to step 2.
2. **Are any requirements, UI states, auth/tenancy rules, config/env keys, logging rules, performance targets, or data contracts ambiguous or conflicting with `CONTEXT.md`?**
   - **Yes** → **STOP (Anti-Yes-Man Gate).** Cite exact gaps (`PRD/DDR` vs `path:line`) and call `ask_question`. Never invent defaults.
   - **No** → Proceed to step 3.
3. **Have you researched any unfamiliar external API/architecture patterns (`search_web`) and verified reusable repo assets in `CONTEXT.md`?**
   - **No** → Run `/index-project` or `/research` first.
   - **Yes** → Write `specs/<feature-slug>.md` and validate it with the black-box validator script.

## Workflow

1. **Ground Against Codebase**: Read DDR/PRD and `CONTEXT.md` end-to-end. Verify exact `path:symbol` for shared UI widgets/components, theme tokens, API clients, schemas, config loaders, and structured loggers.
2. **Classify Facts (`KNOWN` / `OPEN` / `ASSUMED` / `N/A`)**: Copy numbers, schemas, and commands verbatim. Inapplicable sections get `N/A — <reason>`, never silent omission or fake metrics.
3. **Specify Industrial Contracts**:
   - Functional `REQ-###` (Given/When/Then), `INV-###` / `ST-###`, and UI state matrix (`loading`, `empty`, `validation error`, `server/offline error`, `disabled`, disposal).
   - Security & credential hygiene (`SEC-###`: auth/BOLA, strict parsing, idempotency, secret isolation).
   - Configurability (typed startup-validated keys), structured logging (`traceId`, `<REDACTED>`), and performance/complexity budgets (`NFR-###`: N+1 prevention, pagination/virtualization, isolate/worker offload).
   - Traceability Matrix mapping every requirement to a public seam and automated test.
4. **Validate via Black-Box Script**:
   ```bash
   node .agents/skills/to-spec/scripts/validate-spec.mjs --help
   node .agents/skills/to-spec/scripts/validate-spec.mjs specs/<feature-slug>.md
   ```

## Route next

- `READY FOR TICKETS` (multi-slice) → `/to-tickets`.
- `READY FOR TICKETS` (single slice) → `/implement`.
- `NOT READY` → resolve blockers via `ask_question` or `/discover`.

Use [resources/spec-example.md](resources/spec-example.md) as a provenance shape reference only—never copy its domain facts.