# To Spec > Use when settled requirements need a clear execution contract. Applies a lightweight in-session specification automatically for medium jobs and a durable traceable draft when explicitly requested or when complex work needs persistent acceptance evidence. - Skill: `saikaaco/to-spec` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add saikaaco/to-spec` - Raw SKILL.md: https://api.skillmd.com/api/skills/saikaaco/to-spec/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: SaikaAco (https://skillmd.com/u/saikaaco) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/saikaaco/to-spec --- # Traceable To-Spec ## Lineage This is an MIT-licensed adaptation of Matt Pocock's public [`to-spec`](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-spec). It retains conversation-to-spec synthesis without another interview while adding Hermes-specific authority, traceability, coverage, blocking, safety, and persistence contracts. The complete upstream MIT notice is preserved in [`references/third-party-notices.md`](references/third-party-notices.md). ## Overview To-Spec compiles already-settled decisions, evidence, and project context into a reviewable specification. It preserves authoritative source handles, makes negative requirements explicit, and proves coverage. It does not itself create publication, task-creation, or implementation authority. It is a compiler, not an interview or planning loop: ```text clear route: Bounded Grill or settled conversation -> To-Spec large or foggy route: Bounded Grill -> Wayfinder -> To-Spec approved implementation decomposition: To-Spec -> To-Tickets -> optional per-ticket Plan / authorized execution ``` To-Tickets is a separate, explicitly invoked compiler. To-Spec may emit a traceable handoff but never drafts, publishes, labels, or runs tickets itself. ## Adaptive invocation and operating level Choose `LIGHT` or `FULL` before compiling. ### LIGHT — model-invokable, embedded contract Use LIGHT automatically when a concise contract would reduce drift but a persistent specification would be disproportionate. Typical signals include two or more of: - the goal is settled and at least two constraints or acceptance conditions matter; - the job has at least three meaningful steps or touches multiple seams; - the user has already authorized planning, building, shipping, or review and a short requirements check would improve fidelity; - a LIGHT Wayfinder route is ready to become concrete; - scope, out-of-scope, assumptions, or recovery boundaries need to be explicit. LIGHT remains in the current conversation and creates no file, issue, label, tracker item, or durable handoff. Keep it compact: ```text Goal Scope / out of scope Requirements and constraints Observable acceptance Assumptions / gaps Authorized next action ``` LIGHT may be embedded inside an already-authorized task and then return control to that task. It does not create new authority, but it also does not cancel planning or implementation that the user already explicitly authorized. ### FULL — durable traceable draft Use FULL when the user explicitly requests a specification, when a valid FULL Wayfinder handoff is ready, or automatically when any of these hard signals makes durable coverage materially valuable: - the work will likely span sessions or reviewers; - three or more authoritative decisions or source handles must remain traceable; - an external interface, migration, safety boundary, or costly rollback is involved; - persistent acceptance evidence is needed for implementation or handoff. When selecting FULL automatically, announce that choice in one sentence and name the intended artifact path or `chat-only`. Persist only to an already authorized project convention or path. External publication, tracker mutation, labels, notifications, tasks, and implementation remain separately governed by the current user request. ## Authority boundary - FULL produces a `DRAFT` specification unless the user explicitly assigns another reviewed state. LIGHT produces only an in-session contract. - Do not interview the user or reopen settled decisions. - Do not silently choose among unresolved route-changing alternatives. - Do not publish to an external tracker, apply labels, notify collaborators, create implementation tickets, invoke `plan`, implement, commit, or deploy unless that exact downstream action is independently authorized by the current user request. - A specification never creates new implementation authority. After LIGHT or FULL, continue only with downstream actions the user already explicitly authorized; otherwise stop at the contract or draft. - External publication, task creation, planning, and implementation each require explicit authority; one never implies another. ## Accepted inputs Use one or more of: - a Bounded Grill `DIRECT_SPEC` packet; - a settled conversation with identifiable decisions and evidence; - a `wayfinder-to-spec-v1` packet plus its authoritative map and decision tickets; - existing project requirements, policy records, ADRs, or specifications; - relevant codebase and documentation evidence. Do not require a specific tracker or named research skill. Use the tools and source hierarchy available in the active profile. LIGHT may compile an ordinary settled task or LIGHT Wayfinder route without a schema packet. The strict handoff contracts below apply to FULL. ## FULL Grill handoff contract When the source is Bounded Grill: 1. Require `schema: grill-route-v1`. 2. Continue only for `route: DIRECT_SPEC`. 3. Require destination, accepted decision handles or exact accepted values, constraints, negative requirements, evidence handles, suspected fog, out-of-scope boundaries, and persistence status. 4. Treat suspected fog as empty or explicitly non-route-changing. Otherwise return `BLOCKED` and route to Wayfinder. 5. Allow `persistence: pending` only when exact accepted values and actual source timestamps are present; the resulting specification must preserve them as its first durable consumer. For `WAYFINDER`, return the packet for Wayfinder and stop. For `BLOCKED`, preserve the named evidence or authority blocker and stop. ## FULL Wayfinder handoff contract When the source is Wayfinder: 1. Require `schema: wayfinder-to-spec-v1`. 2. Continue only for `outcome: READY_FOR_SPEC`. 3. Require destination, map handle, every current decision handle, scope, out-of-scope boundaries, evidence handles, assumptions/non-blocking deferrals, stale/superseded handles, readiness owner, actual timestamp, and `persistence: confirmed`. 4. Resolve each handle from its authoritative record; do not treat the packet gist as a replacement for ticket rationale. 5. Return `BLOCKED` when the packet is incomplete, stale, contradictory, or not durably persisted. For `DESTINATION_COMPLETE_WITHOUT_SPEC`, report that To-Spec is not applicable and stop. For `BLOCKED`, preserve Wayfinder's blockers and stop. ## Readiness gate For LIGHT, run a compact readiness check and expose material gaps instead of inventing decisions. For FULL, inspect the supplied sources and classify every material gap before drafting. Return `BLOCKED` instead of a specification when any of these remain: - an unresolved decision can change scope, destination, architecture or execution class, supported cohort, authority or safety boundary, dependency structure, or acceptance method; - accepted decisions materially contradict one another; - a required authoritative record is stale, superseded, or unavailable; - critical evidence cannot be obtained without guessing; - the requested output would require authority the user has not granted. For each blocker, return: ```text gap why it changes the route or authority decision/evidence owner recommended route: bounded-grilling | wayfinder | evidence lookup ``` Do not ask the missing questions inside To-Spec. Route them to the owning workflow and stop. Non-route-changing implementation details may remain explicit assumptions or local-spec choices when they are safe, reversible, and testable. ## Source precedence Apply this order: 1. current accepted Wayfinder or project decision records; 2. the user's current explicit direction; 3. applicable project instructions, policies, and requirements; 4. verified repository state and source documentation; 5. explicit assumptions. When a higher-priority source supersedes a lower-priority record, preserve the old handle, mark it stale or superseded, and explain the replacement. Never resolve a contradiction by silently blending incompatible statements. ## Grounding pass Inspect only the relevant context needed to ground the specification: - project instructions and accepted requirements; - authoritative decision records and their current status; - domain vocabulary and applicable ADRs; - current interfaces, seams, behavior, and prior tests; - primary sources for externally constrained facts. Separate: - observed facts with handles; - accepted human decisions with handles; - safe local-spec choices; - explicit assumptions requiring later verification. Do not write code or mutate the inspected project during this pass. ## FULL compilation process 1. Inventory all current decision IDs or source handles. 2. Preserve the exact force of each accepted value, including exceptions, constants, ordering, defaults, retry behavior, negative requirements, and rejected alternatives that constrain implementation. 3. Assign spec-local requirement IDs such as `REQ-001`. These identify requirements only; they never replace or renumber authoritative decision IDs. 4. Draft the specification using the template below. 5. Map every current decision/source handle to its concrete coverage. 6. Audit for omission, weakening, contradiction, unsupported expansion, stale references, and unverifiable acceptance language. 7. Return `BLOCKED` if the audit exposes a route-changing gap; otherwise emit the draft and completion report. Prefer complete coverage over extensive prose. Merge redundant user stories or requirements rather than repeating them. ## FULL specification template ```markdown # Status: DRAFT Generated: Destination/source: ## Problem and destination ## Users and observable outcomes ## Scope ## Out of scope ## Requirements ### REQ-001 — - Requirement: - Source decisions/evidence: - Constraints and exceptions: - Negative requirements: - Observable acceptance: ## Accepted decisions and constraints ## Solution and seams ## Acceptance and verification evidence | Requirement | Observable outcome | Verification method | Required evidence | |---|---|---|---| | REQ-001 | ... | ... | ... | ## Safety, recovery, and authority boundaries ## Assumptions and non-blocking deferrals ## Decision coverage | Decision/source handle | Status | Covered by | Fidelity check | |---|---|---|---| | ... | current | REQ-001 / constraint / out-of-scope | exact / strengthened / gap | ``` Adapt section vocabulary to the domain. For software, seams may be APIs, modules, user interfaces, or integration tests. For non-software work, use the relevant operational boundaries and evidence surfaces instead. ## FULL coverage gate The draft passes only when: - every current authoritative decision/source handle has a row; - every row maps to a requirement, constraint, acceptance item, or explicit out-of-scope disposition; - every negative requirement and material exception remains visible; - no stale or superseded record is treated as current; - every acceptance statement names an observable outcome and evidence method; - every unsupported claim is marked as an assumption; - no requirement expands scope without an authoritative source. Use `gap` rather than pretending coverage when a decision was weakened, omitted, contradicted, or cannot be verified. A route-changing gap changes the result to `BLOCKED`. ## To-Tickets handoff When the specification or LIGHT contract passes its coverage/readiness gate, To-Spec may return this traceable downstream packet without creating tickets: ```yaml schema: to-spec-ticketization-v1 spec_state: LIGHT_READY | DRAFT_READY spec_handle: source_snapshot: source_owner: requirement_ids: [] decision_handles: [] evidence_handles: [] coverage_status: passed grounding_status: passed persistence: none | confirmed decomposition_authority: pending | granted publication_authority: none ``` Rules: - Emit it only after the selected To-Spec readiness and coverage gates pass. - `decomposition_authority: granted` requires the current user to explicitly accept this exact source snapshot for To-Tickets decomposition; otherwise use `pending`. - `publication_authority` is always `none`. To-Tickets must show the complete graph and obtain separate approval bound to that exact graph and backend. - If the specification changes, invalidate the snapshot, coverage evidence, and any downstream draft graph. - Do not invoke To-Tickets automatically. Return the packet and stop unless the current request already explicitly includes ticket decomposition. ## Output and persistence LIGHT stays in chat and reports its compact contract plus the authorized next action; it writes no artifact. For FULL, if the user supplied an authorized local path or the active project has a clear specification convention, write the `DRAFT` there. Otherwise return the complete draft in chat and ask where it should be saved only if persistence is needed. Unless the current user request explicitly authorized the named downstream action, do not: - create a tracker issue or external document; - apply `ready-for-agent` or any equivalent execution-facing state; - mark the specification accepted on the user's behalf; - create implementation tickets or modify a FULL Wayfinder map; - start planning or implementation. After producing the draft, report: - artifact path or `chat-only`; - source handles consumed; - requirement and decision-coverage counts; - assumptions, deferrals, and gaps; - ticketization handoff state (`not-emitted`, `pending`, or `granted`) and source snapshot when emitted; - any external publications, tasks, labels, planning, or implementation actions actually taken, plus their explicit authority source; normally `none`. ## Completion states LIGHT returns exactly one: - `LIGHT_READY` — compact in-session contract is complete and may return to an already-authorized task; - `BLOCKED` — a route-changing decision, contradiction, authority gap, or critical evidence gap remains. FULL returns exactly one: - `DRAFT_READY` — the durable specification and coverage audit are complete; - `BLOCKED` — a route-changing decision, contradiction, authority gap, or critical evidence gap remains. `LIGHT_READY` and `DRAFT_READY` describe contract readiness only. Neither means accepted, published, ready for an agent, or newly authorized for implementation. ## Common pitfalls 1. **Re-interviewing.** Route missing decisions to Bounded Grill or Wayfinder. 2. **Conversation-only synthesis.** Use authoritative source handles. 3. **Summary weakening.** Preserve exceptions, negatives, constants, and rationale pointers. 4. **Prose inflation.** Optimize for complete coverage, not maximum length. 5. **Assumption laundering.** Mark unsupported claims explicitly. 6. **Stale decisions.** Preserve history but compile only current records. 7. **Premature publication.** A draft is local/chat-only without approval. 8. **Execution signaling.** Never apply an agent-ready label automatically. 9. **Ticketization leakage.** A downstream handoff does not draft or publish tickets; decomposition and publication remain separately authorized. 10. **Task leakage.** Requirements and acceptance evidence are not an implementation task list. 11. **Implementation drift.** FULL stops after the draft unless the current request already authorized downstream work; LIGHT returns only to work already authorized. 12. **FULL for every job.** Prefer LIGHT when persistence and complete coverage would cost more than they save. ## Verification checklist - [ ] LIGHT or FULL was selected from observable task signals. - [ ] LIGHT created no file, issue, label, tracker item, or durable handoff. - [ ] Any automatic FULL selection was announced with an authorized path or `chat-only` target. - [ ] Any FULL Grill input passed the `grill-route-v1` contract. - [ ] Any FULL Wayfinder input passed the `wayfinder-to-spec-v1` contract. - [ ] Readiness was checked before drafting. - [ ] No unresolved route-changing decision was silently answered. - [ ] Relevant project and source evidence was inspected. - [ ] Facts, decisions, local choices, and assumptions are distinct. - [ ] For FULL, every current decision/source handle has coverage. - [ ] Negative requirements and exceptions remain explicit at the selected operating level. - [ ] Acceptance outcomes and evidence methods are observable at the selected operating level. - [ ] The output state is `LIGHT_READY`, `DRAFT_READY`, or `BLOCKED`. - [ ] Any ticketization handoff conforms to `to-spec-ticketization-v1`, binds one exact source snapshot, and leaves publication authority `none`. - [ ] To-Spec created no ticket graph, ticket file, tracker issue, or agent-ready label. - [ ] No external publication, label, task, plan, or implementation occurred without explicit authority from the current user request.