Create Engineering Spec

Create Engineering Spec

When to Use

Use when a rough request must become an engineering-facing spec before planning, coding, migration, compliance work, or review. Trigger on requests to create, write, draft, sharpen, decompose, or think through a spec; vague feature asks; product notes that need engineering translation; bug reports that need target behavior defined; and high-consequence domains such as regulated data, billing, telecom, healthcare, financial workflows, legal/audit workflows, security, schemas, migrations, or operational systems.

Do Not Use

Do not use for implementation plans, code changes, task breakdowns, commit boundaries, file edit lists, or quick factual answers. Use a plan skill after the spec is approved.

Do not use for product strategy, ideation, brainstormed opportunity lists, launch copy, release announcements, PR descriptions, commit messages, publishing, tracker updates, setup repair, worktree management, browser/device test execution, or raw feedback/media analysis unless the task is to consume their settled evidence into an engineering spec.

Do not use this skill to coordinate a broad multi-session PRD-to-spec readiness map. If a current PRD/product brief exists but multiple material engineering-truth questions or one broad material engineering-truth question must be resolved before an honest spec can be written, route to create-spec-readiness-map first.

Iron Law

No warrant, no unsupported truth, no spec.

A spec is valid only when durable engineering truth must survive implementation and the selected form resolves a named uncertainty or acceptance gap that can change the next action. A compact Standard spec uses only the bounded contract below. A full engineering spec additionally requires its decomposition, inventory, research, risk, and independent-review gates to be individually warranted and passed.

If a required gate fails, do not substitute the other form or expand ceremony by habit. Emit a blocked packet, perform bounded discovery, or return new concrete escalation evidence to the orchestrator.

If the blocked work is not one missing fact but a broad PRD-to-spec readiness gap, route to create-spec-readiness-map instead of hiding the gap inside a partial spec.

Core Concept

Fit before form. A spec is not a template. It is the engineering truth needed before planning: what must be true, what must never happen, who or what has authority, which constraints apply, what risks matter, what proves acceptance, what shape of scope fits the available appetite, and what the later plan must analyze.

Greenfield fit means researched fit to domain, constraints, authority, options, technologies, operations, security, quality attributes, and best practices. Brownfield fit means researched fit to the existing system: rules, ADRs, current behavior, code, tests, dependencies, contracts, runtime wiring, consumers, compatibility, and operations.

Artifact Boundary

A valid completed spec that is later judged unnecessary remains valid historical work. Preserve it and, when useful, mark it superseded or non-operative. Delete it only with explicit user authority or an existing retention rule that names the artifact class and deletion condition.

User stories are source material only. Convert them into actors, impacts, rules, data concepts, constraints, invariants, contracts, and acceptance evidence.

When a PRD, product brief, or domain note exists, treat its product-domain model as source material to preserve, refine, or explicitly reject with evidence. Do not discard product language just because the engineering spec needs a different structure.

Mandatory Sequence

First run the common warrant gate, then run only the selected form. Do not make compact mean the full internal workflow with fewer headings.

Spec Warrant And Intake Boundary

Before decomposition, consume the orchestrator's assurance decision and confirm that a durable engineering spec is the right artifact.

Consume the accepted scope envelope: Outcome, Non-goals, Target boundary, Acceptance proof, and Expansion or re-plan triggers. The spec may clarify durable engineering truth inside that envelope; it must not enlarge the requested outcome because a broader design looks cleaner, more complete, or more future-proof.

A spec is warranted only when durable behavior, constraints, invariants, authority, contracts, or unresolved choices must survive implementation. A code change, control-artifact change, artifact label, file count, configuration status, delegation choice, or Standard lane alone is insufficient.

Every normative requirement and proposed capability must trace to the accepted outcome, a current named risk or invariant, a required compatibility obligation, or an explicit authority-backed constraint. Reject or record as non-scope an item with no such trace. If newly discovered evidence makes an expansion necessary, return the concrete fact, affected consequence or gate, and changed next action to the orchestrator; do not hide the expansion inside decomposition, risk analysis, an edge case, or a reviewer suggestion.

Approved requirements, scope, deliverables, acceptance criteria, and plan commitments cannot be rewritten to justify a discovered deviation. Research, review advice, internal reclassification, or routing back to this skill does not grant user approval. Stop dependent work for a user decision before amending those commitments; distinguish a proposed amendment from approved truth and keep status/evidence updates separate. Preserve existing authority for in-scope decisions and repairs. Mention and record discovered issues under the project-rules discovery contract; unrelated entries remain deferred, not new requirements.

Name the uncertainty or acceptance gap the spec can resolve and how its result changes the next action. If no result can change the next action, stop this phase and reference the existing sufficient evidence. If Spec warranted: no, do not create a spec merely because this skill was invoked; preserve any valid completed spec and return to the recorded route.

Use the compact Standard form when the durable truth is bounded and the full-form discovery and artifact-review gates are not both independently warranted. The compact minimum is: the reason durable engineering truth must be preserved; objective and current-versus-target behavior; target and non-target boundaries; directly applicable sources and authority conflicts; observable requirements and acceptance evidence; material risks or escalation triggers; and downstream handoff facts. Decompose only facets that can change those fields, inspect only sources governing the affected behavior, and research only material current external facts. Do not run generic eight-facet expansion, broad risk inventories, broad source inventories, unrelated research, or independent spec review without a separate named source, authority, contract, high-consequence, or explicit-request warrant.

Use the full form only when its deeper discovery and review controls are individually warranted. Preserve current evidence, source and authority traceability, material risk analysis, full discovery, and independent artifact review at the depth justified by those warrants.

This skill may challenge an insufficient incoming warrant, but it may escalate only by returning newly discovered concrete evidence, the affected consequence or gate, and the changed next action for an updated orchestrator decision. Skill or agent preference, artifact type, file count, or generic uncertainty cannot silently reclassify the task.

Route or de-escalate instead when the request is:

• direct local work with known behavior, known cause, narrow blast radius, and concrete verification;
• product strategy, PRD/product truth, ideation, or opportunity discovery without a selected and authorized direction;
• broad PRD-to-spec readiness work where a current product source exists but multiple material engineering-truth questions remain, or one broad material engineering-truth question needs durable investigation tickets before this skill can synthesize requirements;
• post-ship communication, promotion, changelog, release copy, PR prose, commit prose, publishing, or external metadata work;
• diagnosis where a failure cause, target behavior, or proposed fix is not yet supported;
• architecture judgment, ADR capture, implementation planning, execution, testing, setup, git/PR, or documentation work owned by another skill.

Failure output: Blocked: engineering spec is not warranted or the selected form cannot resolve a named gap: <reason>. Owning path: <direct work/PRD/create-spec-readiness-map/ideation/diagnosis/architecture/plan/docs/testing/git/PR/publishing/other>.

The mode, inventory, research, domain-model, risk, scope-shaping, and full review sections below define the full-form branch. A compact Standard spec uses only the bounded work stated above and the compact output contract.

Mode Classification

There are only two workflows.

A new component inside an existing platform is brownfield first. If the prompt does not reveal the mode, inspect context or ask one mode question. Do not create a third workflow.

Inventory Rules, ADRs, and Skills

Before planning research or writing any requirement, inventory the constraints and reusable knowledge that change what "correct" means for this spec:

• repository instructions, rules, and policies that govern the affected surfaces;
• ADRs and prior technical decisions that constrain or pre-decide parts of the work;
• existing specs, requirements, audits, dependency maps, and design docs;
• available project or installed skills for the relevant stack, language, framework, database, testing, security, observability, migrations, or domain;
• available specialist agents for source discovery, codebase research, and external/library research.

You MUST load the relevant skills before writing requirements that depend on them. If a skill exists for a stack element or concern, load it or hand it to the research/discovery worker; if none exists, use authoritative current docs and record that no skill was available. Surface and resolve conflicts between rules, ADRs, and the request before they reach a normative requirement.

Resolve skill and agent names against the actual available capability list, including namespaced variants. Do not guess short skill names or assume a capability exists because a roadmap, old plan, or prior conversation mentioned it.

Classify unavailable skills, agents, tools, or source-access paths as:

• required blocker: the missing capability or source access prevents authority, current behavior, or acceptance evidence from being established;
• fallback-covered: direct inspection, current official docs, or another available skill can provide equivalent evidence;
• optional capability: useful but not needed for spec validity.

Completion condition: the spec can state which rules, ADRs, and skills were applied, which were irrelevant, and which were missing but required.

Research Rule

Research is not “search everything.” For a compact Standard spec, research only a material current external fact that can change the compact contract. For a full spec, plan research from the warranted decomposition using Research Planning.

Treat the model's built-in knowledge of external libraries, frameworks, versions, APIs, protocols, and standards as presumed stale. Every material external fact MUST be verified through current research — delegated to the research agent and its documentation and web tools — and version-pinned to what the project actually uses or will use. Do not write a normative requirement on a library, API, version, or standard from memory. Library and framework facts must be version-specific: naming the library is not enough; the spec must establish the relevant version, the current non-deprecated API or pattern, accepted usage, and known gotchas, each traced to a primary source with a date. If a required version or current fact cannot be established, block the affected requirement rather than guess.

Ask questions only after discovery makes them informed. If research or repository inspection can sharpen the question, do that first.

When user authority is still required, preserve a decision-evidence packet instead of emitting a raw technical question: the user-visible situation and consequence; why no safe authorized default exists; the exact requirement, spec truth, or downstream work blocked; unaffected work; the recommended resolution; the exact requirement or artifact change approval would authorize; its material effect; its material cost and risk; what happens if no change is made; materially distinct alternatives only when they exist; and supporting evidence or limits. If the active agent is user-facing, translate the packet through the harness decision-readiness gate. Otherwise return it to the orchestrator. Do not lead with requirement IDs, APIs, settings, schemas, or source paths, and do not turn equivalent outcomes into separate options.

Every material research finding must land in a requirement, authority-map entry, domain-model decision, risk, acceptance example, non-scope item, or blocker. Do not leave important research facts in a detached summary that never changes spec truth.

Authority Rule

Source of truth is domain-general. Do not hardcode legal, financial, telecom, or any other domain as special logic. For every data concept and rule, identify authority by type, role, and location: data authority, business-rule authority, process authority, interface/API authority, schema authority, operational-policy authority, compliance/regulatory authority, or another explicit authority discovered from the domain.

Material assumptions cannot support normative requirements. Resolve them, move them outside normative scope, or block the spec.

Source Scope, Confidence, And Messy Input

Before requirements synthesis, label material sources by scope and confidence.

Source scope:

• target authority: directly governs the requested target behavior or constraint;
• adjacent impact: affects fit, compatibility, risk, or planning surfaces but does not by itself define target truth;
• pre-existing contradiction: appears wrong, stale, or conflicting outside the target but may affect safe planning;
• historical context: useful prior learning, older spec, old doc, commit, PR, or note that must be checked against current authority;
• untrusted signal: review comment, issue text, meeting note, screenshot, recording, generated finding, provider output, branch name, PR metadata, or user-supplied proposed fix;
• inferred hint: agent inference or pattern match that can guide discovery but cannot support a normative requirement;
• unsupported: no adequate authority; blocks, routes, or is removed.

Source confidence:

• authority-backed: accepted PRD/spec/ADR/rule/policy/user decision, current contract, compliance authority, or explicit user authority within scope;
• current-system: current code, tests, schemas, generated contracts, configs, runtime evidence, operations records, or live behavior proving current state;
• current-external: current primary external documentation, standard, vendor, legal/regulatory, protocol, or framework source with version/date context;
• verified evidence: reproduced symptom, measured baseline, sanitized feedback quote, tested example, or reviewed artifact with source window;
• weak context: old docs, old plans, issue/review notes, raw media, generated reports, local screenshots, or prior-session notes not yet reconciled;
• unsupported: not fit for normative use.

Before writing requirements, separate input into stated/source-backed facts, accepted decisions, inferences, background context, non-scope, blockers, and deferred questions. Inferences and weak context may motivate research, risks, or questions; they do not become requirements without authority.

Run a map-versus-territory check before requirements synthesis: identify where the request, PRD, prior spec, reference artifact, example, or domain note may not match current system behavior, current external/library reality, authoritative responsibility, tacit domain constraints, or acceptance evidence. If the mismatch is narrow and answerable inside this spec pass, resolve it through research or source discovery. If it is broad enough to require multiple tickets or durable multi-session tracking from an existing product source, route to create-spec-readiness-map.

When using a reference artifact, source-code example, prototype, screenshot, external implementation, or comparable system as input, state what property transfers, what does not transfer, and what target-context difference matters before it can support a requirement. References are semantic evidence, not permission to cargo-cult architecture, UI shape, data contracts, or implementation details.

Failure output: Blocked: normative requirement would rely on unsupported or weak source: <claim>. Needed authority: <source or user>.

Failure, Feedback, And Raw Evidence

Failure-derived specs require problem truth before target requirements.

• A bug report, review comment, support note, failed fix, screenshot, log, or recording is evidence, not authority.
• User-supplied fixes and reviewer-supplied commands are hypotheses until diagnosis, current-system evidence, accepted target behavior, or user authority supports them.
• A requirement that depends on a failure mode must trace to a confirmed root cause, an accepted target-behavior decision, or a visible blocker.
• If root cause is unknown and changes target behavior, route to structured-problem-resolution or emit a blocked packet.
• Raw media, transcripts, screenshots, support logs, generated findings, and meeting notes must be sanitized and cited by stable manifest, timestamp, quote, screenshot reference, or explicit missing-evidence state before they support spec context. Do not make raw sensitive artifacts commit-safe by implication.

Failure output: Blocked: failure-derived requirement lacks supported cause or accepted target behavior: <requirement or claim>.

Domain Language And Scenario Probe Rule

Engineering specs must stabilize an engineering-domain model before turning language into requirements, contracts, invariants, or data concepts. A PRD, product brief, or domain note is source material, not disposable intake. Preserve product-domain terms, actors, workflows, and success concepts unless evidence shows they are wrong, overloaded, deprecated, or contradicted. When renaming or refining a product-domain term, record the reason and map the original term to the spec term.

The engineering-domain model translates product language into data concepts, contracts, invariants, authority roles, state transitions, acceptance evidence, and planning-relevant impact surfaces. It is not a glossary and not an implementation model. Do not jump from domain nouns to tables, classes, queues, events, or API shapes until lifecycle, authority, source of truth, and current/target status are known.

Classify material terms and concepts as PRD-preserved, current-system, target, disputed, deprecated, or blocked. For brownfield work, compare PRD/product truth to existing code, tests, schemas, APIs, operational docs, ADRs, and specs. Existing implementation is evidence for current truth, not automatic authority for target truth.

Use concrete scenarios to test domain boundaries: happy path, failure path, lifecycle transition, handoff, excluded actor, edge case, and authority conflict. If a scenario changes the meaning of a term, state, process, or invariant, update the decomposition and domain model before synthesizing requirements.

For brownfield work, cross-check important domain claims against code, tests, schemas, APIs, operational docs, and existing ADRs/specs. If the request says partial cancellation is possible but the code only cancels whole records, surface the contradiction instead of choosing silently.

Do not create or update a separate glossary file from this skill unless the user explicitly asks for that artifact. Capture the domain model inside the spec output and hand off lasting technical decisions through create-project-adr when they meet the ADR bar.

Risk and Impact Rule

Spec-level impact is not implementation planning. The spec must identify impacted contracts, data concepts, processes, actors, authority roles, downstream consumers, trust boundaries, operational constraints, and acceptance evidence. The implementation plan later decides exact files, units, sequencing, tests, and commits.

For a compact Standard spec, record only material risks or escalation triggers that can change requirements, acceptance, or the next route. Do not generate a broad risk inventory. For a full spec, risk analysis must be structured: run a pass across security/attack, reliability/failure, compliance/regulatory, and operational dimensions, with reasoned no impact entries.

For reporting, analytics, observability, dashboards, generated reports, or data-derived summaries, include metric/event authority, canonical source, instrumentation status, query or source window, freshness/ingestion lag, missing-data behavior, privacy constraints, query safety, and downstream consumers when those facts affect requirements or acceptance.

For runtime, browser-visible, local-development, platform-specific, or agent/workflow systems, include the relevant app root, route/screen, launch or runtime authority, environment, current observed behavior, automation limits, human-only verification, action responsibility, context visibility, permission boundary, lifecycle interruption/recovery, and agent-native acceptance evidence at spec depth.

Scope Shaping Rule

An engineering spec must shape scope deliberately instead of listing an idealized feature set. Borrow the useful Shape Up discipline without weakening the spec gates:

• Envelope before feature set: preserve the accepted outcome, non-goals, target boundary, acceptance proof, and expansion triggers. Do not turn implementation convenience, generic completeness, or possible future use into normative scope.
• Problem before solution: state the current baseline, who or what is affected, and the cost of the status quo before writing requirements.
• Appetite before scope expansion: identify the delivery appetite or decision budget when the user or project provides one. Appetite is how much the work is worth, not an implementation estimate.
• Fixed appetite, variable scope: when the desired solution does not fit the appetite, propose the smallest scope decision with its consequences. Cutting or deferring approved scope requires a user decision before changing the spec; do not reduce acceptance criteria or expand the time budget to justify a deviation.
• Scope additions must declare their trade: when adding or expanding a capability, state what it displaces, consumes, defers, or forces into explicit scope expansion. If nothing is displaced, explain why the appetite or required outcome still justifies the added responsibility.
• Rough but solved: define the target behavior, interfaces, constraints, and acceptance evidence clearly enough for planning, while leaving implementation order, file choreography, and code to the plan.
• Rabbit holes are risks: identify likely derailers, unknowns, dependency traps, edge cases, and hidden complexity; resolve them through constraints, explicit mitigations, research, deferral, or blockers.
• Lifecycle responsibility cost is scope: material capabilities must account for build, test, maintenance, documentation/support, operational, and future-change burden at spec depth. Do not treat these as plan-only concerns when they affect whether the requirement belongs.
• No-gos are first-class: record excluded capabilities, edge cases, related features, or nice-to-haves that would change scope, risk, or appetite.

If appetite is unknown and it materially changes scope, do not invent it. Ask one informed blocking question or produce a spec that marks appetite as unresolved and keeps scope conservative. If appetite is irrelevant because the request is a hard requirement, operational fix, compliance obligation, or bug target, state that and shape by required outcome, risk, and acceptance evidence instead.

Deferred questions are safe only when the answer cannot change normative requirements, authority, scope, risk severity, compatibility, or acceptance evidence. Otherwise they are blockers, not deferred questions.

Delegation Rules

Use isolated discovery or research workers only when the incoming delegation warrant or new concrete evidence shows that isolation, parallelism, specialist capability, or context focus materially improves the result relative to re-derivation cost. Delegation is read-only unless artifact mutation is explicitly approved, and delegation does not create a spec or full-form warrant.

Delegate source discovery for scattered rules, ADRs, existing specs, dependency maps, plans, research notes, prior decisions, authoritative documents and responsible components, standards, or policies. Required return: sources, precedence, conflicts, responsibility/authority status, and exact evidence.

Delegate codebase discovery for brownfield work. This is mandatory in brownfield, either directly or through delegation. Required return: current behavior, current implementation state, responsibility, dependencies, tests, contracts, impact surfaces, consumers, compatibility constraints, and likely breakage paths.

Delegate external research when material behavior depends on current library, framework, protocol, standard, vendor, legal, regulatory, security, operational, or domain best-practice facts. Required return: primary sources, facts, caveats, dates/versions, confidence, and how each fact affects the spec.

When delegated discovery, research, or review returns long or structured evidence, preserve exact sources and read any returned artifact or evidence packet before relying on the summary. Compressed worker summaries are not authority by themselves.

Do not delegate final scope decisions, source-of-truth conflict resolution, assumption approval, requirement synthesis, or conversion of uncertainty into decisions. The orchestrator owns the spec.

Output Contract

Use Spec Output Contract. Emit the compact Standard form when its bounded gates pass, the full form only when every individually warranted full-form gate passes, and the blocked packet when a required gate fails.

When spec evidence will feed planning, ADRs, commits, PRs, publishing, implementation, or review, hand off the spec path, slug, status, mode, review state, source/authority gaps, requirement IDs, acceptance IDs, risk IDs, authority IDs, non-scope, blockers, and planning-relevant impact surfaces. Do not include implementation units, file lists, git commands, PR mutation, CI watch, publishing, or tracker mechanics in the spec.

Independent Spec Review

A spec is upstream, so independent review is valuable when a separate review warrant passes. Warrant spec review for an explicit request or a named source, authority, contract, or high-consequence acceptance gap that a fresh reviewer can resolve. Code change, artifact type, Standard form, file count, or author preference is not a review warrant. When warranted, the reviewer must be fresh and independent; if unavailable, mark the spec Proposed — independent review unavailable. When not warranted, record the reason and do not manufacture a review phase.

When review is warranted, the reviewer receives the original request, selected form, draft spec, directly applicable source/authority evidence, named review gap, and all discovery, research, risk, or decomposition evidence actually used. A full-form review also receives the complete decomposition, rules/ADR/skill inventory, source/authority map, research record, and risk register. Do not create missing full-form material solely to fill a compact-spec review packet.

The reviewer packet must also include source-scope/confidence labels, known blockers, deferred questions, acceptance-evidence modality, unresolved source conflicts, and any stale prior artifacts used or rejected.

For a compact Standard spec, the reviewer validates the compact minimum, directly applicable authority, observable requirements/evidence, material triggers, boundaries, and the named review gap. The reviewer must not demand generic eight-facet decomposition, broad risk/source inventories, unrelated research, or full-form sections without a separate warrant.

For a full spec, the reviewer MUST validate:

• every material facet of the request is decomposed and addressed; nothing material is silently dropped or narrowed;
• the spec faithfully respects the actual request and does not substitute a different problem;
• every normative requirement traces to a real authority or source, not an unresolved assumption;
• every external library, framework, version, API, protocol, or standard claim is backed by current, version-specific research, not model memory, and is not deprecated;
• applicable rules and ADRs were found and respected, and conflicts were surfaced rather than buried;
• the available skills for the stack and domain were loaded and applied;
• PRD/product-domain inputs are preserved, refined, or rejected with evidence, and current-vs-target terminology conflicts are surfaced;
• the risk register honestly covers the required dimensions, with reasoned no-impact entries rather than generic prose;
• every requirement has acceptance evidence and is testable;
• assumptions are labeled and do not prop up normative requirements;
• no implementation order, file choreography, or code has leaked into the spec;
• blocking questions are genuinely resolved, not papered over.

Each reviewer finding must include finding type, affected section or ID, evidence, confidence anchor, consequence, whether it blocks readiness, and suggested repair when concrete. Finding types include decomposition gap, source/authority gap, research-currency gap, domain-model conflict, brownfield-fit gap, stale-source conflict, risk/impact gap, acceptance-evidence gap, implementation leakage, scope drift, and unresolved blocker.

Resolve every finding with one disposition: revised, revised-differently, answered-no-change, invalid-with-evidence, declined-with-harm, deferred-non-blocking, or blocked-needs-decision. Do not mark the spec ready while any valid material finding is unresolved. If findings cannot be resolved, emit a blocked packet.

Suppress style preferences, implementation-plan details correctly deferred from the spec, upstream product questions already settled by authority, speculative future work without impact evidence, and pre-existing code issues outside the spec target unless they create a source conflict or planning risk.

Decision Capture (ADRs)

A spec encodes decisions — chosen direction, boundaries, authority, technology direction, and rejected options. Once the spec passes its gates, surface the significant decisions it embeds and offer to record them as ADRs.

Apply the ADR bar selectively. A decision qualifies only when reversal would be meaningfully costly or risky, a future maintainer would reasonably ask why this path was chosen, and the choice reflects a real trade-off among alternatives. Do not ADR trivial, easily reversible, obvious, purely product-scope, or single-path choices.

Present qualifying decisions to the user; the user confirms which graduate to ADRs (an offer, not a gate). Create each confirmed ADR using the create-project-adr skill — one decision per ADR; do not write ADRs freehand. Reference any ADRs created from the spec.

Rationalization Table

…(truncated)