# To Spec > Produce an evidence-backed four-file implementation spec for one bounded software change, using consequence-calibrated contract closure so reachable behavior is decided without over-specifying local work. Use when a grounded task must become an implementation handoff. Triggers: to-spec; write the spec; hand this off. - Skill: `hburaktasyurek/to-spec` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add hburaktasyurek/to-spec` - Raw SKILL.md: https://api.skillmd.com/api/skills/hburaktasyurek/to-spec/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: hburaktasyurek (https://skillmd.com/u/hburaktasyurek) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/hburaktasyurek/to-spec --- # to-spec ## Purpose Turn one grounded software task into a production-ready specification that an implementation agent can execute without inventing a structural contract. The finish condition is not merely four files. The cluster must be complete for the task's reachable consequences, internally consistent, proportionate to the change, and independently verifiable. This skill is the only spec-byte author. Parent, review, and ad-hoc hole-closing do not write spec files. Read `references/outcome-lock.md` and **freeze** its four boundary fields. Do not copy that reference into the spec. ## Inputs and authority Outside Codex adapter mode, use the complete conversation, `task-groundwork` result or equivalent grounded frame, and authoritative task artifacts. Require one bounded outcome, explicit scope/non-goals, acceptance or stop conditions, and an unambiguous output root. Do not restart groundwork when those are already present. When the invocation includes `Adapter: codex-task-to-spec`, verify the named packet manifest and every artifact hash before work. Use only the named task, frozen lock, inventories listed by the immutable `Evidence set`, current spec, complete reports listed by the immutable `Report set` when present, and every owner-resolution JSON listed by `Authority resolutions:` when present. Parent prose, summaries, correction recipes, and conversation memory are not authority. Use the supplied spec identity and receipt output path. When that adapter invocation has `Stage: resolution-check`, read the named question-resolution artifact and return only: ```text Resolved: yes | no Lock: changed | unchanged Resume: task-groundwork | to-spec | commit | review-stage Basis: | sha256: ``` Verify the resolution JSON's source role/stage/mutation and `calling_phase`. For normal authoring, an unchanged lock returns `Resume: to-spec`. For a receipt-only source, return its recorded `commit` or `review-stage` calling phase only when the current spec remains byte-valid under the answer; otherwise return `to-spec`. A changed lock returns `task-groundwork`. Stop after this resolution response; it overrides every normal spec deliverable, receipt, and report rule below. When an adapter envelope sets `Mutation: receipt-only; spec forbidden`, verify the current packet and four-file spec manifest, leave every spec byte unchanged, and regenerate only the supplied closure receipt against that packet. If the receipt cannot be truthful without changing the spec, return `BLOCKED`; do not silently promote this call into a rewrite. Resolve premise types with the source that owns them: - intended behavior: latest explicit user decision, then the most specific binding task/acceptance contract; - current behavior: live code, schema, configuration, tests, and call paths; - external behavior: version-relevant primary documentation; - conventions: repository instructions and repeated current patterns. History, names, comments, and analogous code are supporting evidence, not authority. When sources conflict, expose the conflict rather than silently choosing one. Validate a grounding handoff; do not trust its readiness label. Freeze the **Outcome lock** fields—owned outcome, existing owner/path, neighbor boundary, accepted residual—and verify any remaining question yourself. Investigate what authoritative evidence can decide and preserve behaviorally equivalent local choices as implementation freedom. If evidence cannot decide a choice that changes observable behavior, scope, ownership, state, recovery, or safety, ask the human and wait; do not save a partial spec. Ask one concrete question at a time in plain language. Explain the viable choices and their evidence-backed consequences. Continue the conversation if the answer remains incomplete. Do not return ordinary technical consequences to the human when binding rules and repository evidence already determine them. ## Proportional closure Read [`references/contract-closure.md`](references/contract-closure.md) completely for every task and apply it before writing prose. Calibrate depth from the worst credible consequence reachable through the changed path, not a task label, diff size, author confidence, or apparent simplicity. Trace every reachable task-owned material consequence. Collapse behaviorally equivalent rows and omit systems, axes, and matrices that binding evidence does not place on the changed path. The same closure rule applies to every call. ## Procedure ### 1. Freeze the task contract Record privately: - controlling request and authority source; - frozen Outcome lock: owned outcome, existing owner/path, neighbor boundary, and accepted residual; - verified evidence, bounded implementation freedoms, and any question that still needs a human decision; - exact spec root—`agent-os/specs` by default, or the approved alternative—and a clear timestamped slug. Do not save a partial cluster while a necessary human decision or promoted adjacent concern remains. Ask and wait; do not write spec bytes to paper over it. ### 2. Inspect enough evidence Inspect the relevant production code, tests, schema, configuration, history, repository instructions, and inventory before stating current facts. Cite file-backed claims with verified paths and exact line ranges. Attribute conversation decisions without fabricated file citations. Support absence or uniqueness claims with a search across plausible owners. Label a non-decision evidence gap as `⚠️ UNVERIFIED` everywhere it affects the cluster. A material decision may not be hidden under that label. ### 3. Use the existing owner, then close behavior Before closure, quote the frozen boundary. For every proposed major behavior, decide whether the task owns it, an existing landed path owns it, or it belongs to neighboring work. A public interface, persistent state, transaction/recovery protocol, idempotency identity, provider operation, cross-component identity, or lifecycle branch needs Outcome-lock authority as the owned outcome or an existing owner/path. Current-system evidence may prove a frozen observable is unreachable without that path; it cannot add an observable. Local mechanism ownership does not authorize absorbing a neighbor's create/replace/cancel, a new framework, or neighboring work. Prefer the named landed owner. Absence of an applicable local interface is not permission to invent a parallel machine. If evidence does not decide whether to expose that entry now or leave the work with a separately owned task, ask the human. Compare every grounded viable minimal path. Choose the safe route that calls landed owners and adds the fewest task-owned states and boundaries. If no safe bounded route exists, stop without saving and ask the human; never silently select a framework. Once a **call** is selected, its observable failure path remains mandatory. If the selection is wrong, stop and ask; do not invent extra identities, stores, or recovery rows to make the wrong call work. A typed input's full representable range is not authority to add normative branches or acceptance tests. Specify only values that the Outcome lock or current-system evidence places on the changed path; leave other input behavior unchanged and unowned. Prove the direct changed path, its observable result, and one counterexample when exactness matters. Build the proportionate closure model required by `references/contract-closure.md`. Decide, reject, or deliberately leave as bounded implementation freedom every reachable **task-owned** material row. If a row changes product behavior and no authority selects it, stop before drafting. Do not confuse a clean name, plausible API, happy-path test, or green suite with contract closure. Verify that every selected public producer result is constructible, accepted by its consumer, preserves required identity/state, and has an oracle that can distinguish the unsafe alternative. Treat downstream consumer failure as a separate row whenever the selected call can reject, throw, or partially apply an effect. ### 4. Draft exactly four files Create one folder at `/YYYY-MM-DD-HHMM-/`, where the recorded root defaults to `agent-os/specs` only when no alternative was approved. The folder contains exactly: - `shape.md`: what this builds, verified key interfaces, data/control flow, canonical decisions and invariants, and product-focused out of scope; - `plan.md`: observable acceptance criteria mapped to named `shape.md` and `standards.md` sections; ordered implementation tasks; dependencies; risks; - `references.md`: sources actually examined, exact supporting facts, decisions, discrepancies, evidence limits, link audit, and exact unverified count; - `standards.md`: only source-backed naming, structure, anti-pattern, test, and acceptance-critical assertion rules relevant to this task. Each implementation task names owner, files/change, validation, dependencies, and independently reviewable outcome. Order tasks by executable dependency and identify the first integration slice. Decomposition organizes the plan; it does not substitute for behavioral closure. Keep the cluster proportional. A one-literal local change still gets four files, but they should each be short: target no more than about 800 words across the cluster unless a task-owned discrepancy or validation detail makes the extra text necessary. Coalesce criteria that share one observable contract. `references.md` includes only controlling sources, material decisions/discrepancies, evidence limits, link results, and the unverified count; omit routine command narration and history that do not change the handoff. Do not repeat the same rule in several long forms, reproduce skill instructions, narrate the investigation, or add gates for excluded systems merely to make the spec look rigorous. ### 5. Validate the final cluster Before saving, draft all four files and then audit the cluster as one artifact: 1. Every normative rule has one canonical home and no conflicting paraphrase. 2. Every changed boundary traces from producer/input through public result and consumer success/failure to state/effect; reverse-trace each acceptance oracle to that path. 3. Every quantified criterion (`every`, `only`, `exactly`) is proved over its full stated set, not representative examples. For a load-bearing universal or negative claim, identify whether that set is closed, self-bounded, or open-world under `references/contract-closure.md`; a finite current inventory cannot silently stand in for an open-world proof. 4. A counterexample changes one material variable and fails for the intended reason when exact type, value, state, ownership, or side effect matters. Keep it independent of the enforcement representation when correlated fixtures could repeat the same false premise. 5. Every implementation task can start without choosing a missing structural contract; non-material freedom remains visibly non-canonical. 6. Scope, interfaces, matrices/tables when used, examples, tests, tasks, and out-of-scope clauses agree. 7. Every emitted relative path and Markdown heading link resolves in the saved cluster. Reread all four final files after the latest edit. If the audit exposes a new decision or contradiction, repair it or stop before saving; do not leave a known hole for review to rediscover. Validation must state what each check proves and does not prove. Do not claim future implementation tests ran. Avoid brittle byte-level or shell gates that the task does not require. ### 6. Save, report, and stop Save the four-file cluster. Return the folder path, a one-line summary of each file, the exact `⚠️ UNVERIFIED` count, and confirmation that no implementation was performed. Stop after the specification. Do not independently review it, implement it, change workflow documentation, mutate Git, open a PR, install, or merge. In Codex adapter mode, also write the conditional closure receipt defined in `references/contract-closure.md` to the exact supplied path, then return that path and hash with the normal folder result. The receipt lives outside the spec folder and is not a fifth spec file or a review verdict. Do not commit; the adapter parent owns the later commit stage. On any in-lock rewrite, read every supplied complete review report and decide each current finding as accepted or evidence-backed refuted. Replace the cluster in place as the same spec identity; close every accepted root family and its recorded consequence surface in one rewrite, not one visible manifestation. Do not open a parallel spec folder or leave accepted siblings for a later pass. In Codex adapter mode, bind each finding back to the frozen authority before writing. If closure stays inside the owned outcome or existing owner/path, rewrite it. If it requires a neighbor outcome, new durable owner, or lock enlargement, do not write that change; return exactly one non-empty single-line `Question: ` and no second `Question:` line. The adapter treats the entire immutable returned bytes as evidence. ## Boundaries - Do not change the task contract to make specification or validation easier. - Do not silently select material product behavior or architecture. - Do not absorb a neighbor's outcome or invent a parallel machine because a reviewer says it is necessary. - Do not force a full cross-product where variables cannot vary independently or do not change behavior. - Do not treat later `adversarial-spec-review` or `spec-readiness` as a reason to defer a hole already visible during authoring. - Human approval is required before changing the spec root, deferring a material decision, expanding scope, accepting a materially weaker validation route, implementing, committing, pushing, installing, or merging.