to-spec · diff

git:20261118.549ccf7 to git:20261118.581e4cd

23 added, 34 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: to-spec
- description: Converts a confirmed Discovery Decision Record or PRD into a grounded, unambiguous technical specification (specs/<slug>.md) with provenance, reusable codebase touchpoints, security/failure contracts, and requirement-to-test traceability. Use when planning a multi-slice feature or auditing a PRD before ticketing.
+ 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 (Grounded Technical Specification)
+ # To Spec (Industrial-Grade Grounded Specification)
- Transform a confirmed Discovery Decision Record (`docs/discovery/<slug>.md`) or user-provided PRD into an unambiguous specification at `specs/<feature-slug>.md` using [resources/spec-template.md](resources/spec-template.md).
+ 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. Never invent a spec from vague chat memory.
+ - **No** → Stop and run `/discover` (or built-in `/grill-me`) first.
- **Yes** → Proceed to step 2.
- 2. **Are any requirements, UI states, auth rules, data contracts, or repo seams ambiguous or conflicting with `CONTEXT.md` / existing code?**
- - **Yes** → **STOP (Anti-Yes-Man Gate).** Do not fill unknowns with plausible prose. Cite the exact gap (`PRD/DDR` vs `path:line`) and call `ask_question` (or route back to `/discover`).
+ 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. **Are the public seams, reusable codebase components/helpers, and exact verification command verified from the repo?**
- - **No** → Read `CONTEXT.md` (run `/index-project` if empty) and target manifests/files first.
- - **Yes** → Write `specs/<feature-slug>.md` and run the validation gate below.
-
- ## Source priority (on conflict, STOP and ask the user)
-
- 1. Explicit user decision in this session.
- 2. Confirmed `DEC-###` in `docs/discovery/<slug>.md` (or confirmed PRD).
- 3. `CONTEXT.md` invariants & `docs/adr/`.
- 4. Actual repository code & manifests (`path:line`).
- 5. Live primary docs via `/research`.
- 6. Explicitly approved `ASM-###` (never an unapproved guess).
+ 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.
- ## Specification workflow
+ ## Workflow
- 1. **Audit Inputs & Ground Against Repo**:
- - Read the DDR/PRD and `CONTEXT.md` end-to-end.
- - Inspect existing UI primitives, hooks, schemas, API routes, and DB tables that overlap with the feature. Record exact `path:symbol` reuse targets.
- 2. **Build Fact Ledger (Internal)**:
- - Classify every requirement/NFR/control as `KNOWN` (source cited), `OPEN` (blocking question), `ASSUMED` (user-approved `ASM-###`), or `N/A` (one-line rationale).
- - Never invent latency budgets, endpoints, columns, or error codes. If inapplicable (e.g., DB migration on a UI-only filter), write `N/A — <reason>`.
- 3. **Author `specs/<feature-slug>.md`**:
- - Define `REQ-###` (Given/When/Then), `INV-###` / `ST-###` (illegal states unrepresentable), `SEC-###` (auth/tenancy/parsing/idempotency), `ERR-###` (status/code/recovery), UI state matrix (if UI), `NFR-###` (where applicable, exact units), reusable codebase assets, and the **Traceability Matrix** mapping every ID to a public seam and test.
- - Keep `Status: draft` and `Readiness Verdict: NOT READY` if any ticket-blocking `OQ-###` remains.
- 4. **Validation Gate (Before Marking `READY FOR TICKETS`)**:
- - Every `REQ-###` cites a source and maps to a public seam and test.
- - Every `INV-###`, `SEC-###`, and `ERR-###` has a test/owner/recovery path.
- - Every reusable UI/utility dependency references real repo paths.
- - Zero vague qualifiers (`fast`, `robust`, `for now`, `TODO`) or unresolved blocking `OQ-###`.
+ 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 listed blockers via `ask_question` or `/discover`.
+ - `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.