Spec Document Designer

Spec Document Designer

Purpose

Turn a framed request or synthesized research into a repository-native spec.md that is honest, stable, and ready to hand off into mandatory specification review without turning it into a PRD, a design bundle, or a task list.

Outcome-First Operating Rules

• Start by naming the skill-specific outcome, success criteria, constraints, available evidence, and stop rule.
• Treat workflow steps as decision rules, not a ritual checklist. Follow exact order only when this skill or the repository contract makes the sequence an invariant.
• Use the minimum context, references, tools, and validation loops that can change the deliverable; stop expanding when the quality bar is met.
• Before acting, resolve prerequisite discovery, lookup, or artifact reads that the outcome depends on; parallelize only independent evidence gathering and synthesize before the next decision.
• Prefer bounded assumptions and local evidence over broad questioning; ask only when a missing fact would change correctness, ownership, safety, or scope.
• When evidence is missing or conflicting, retry once with a targeted strategy or label the assumption, blocker, or reopen target instead of treating absence as proof.
• Finish only when the requested deliverable is complete in the required shape and verification or a clearly named blocker/residual risk is recorded.

Scope

• draft a fresh spec.md when the task is mature enough for specification
• normalize existing drafts that are too thin, too bloated, or shaped like a foreign template
• choose the right section depth for the task while staying inside the repository's artifact model
• translate useful coverage prompts from external spec workflows into repo-native sections
• keep blockers, assumptions, inline Risk Challenge or clarification outcomes, validation hooks, and handoff links visible before specification review
• keep the handoff focused on the current decision frontier: record downstream consequences that matter, but do not promote every visible consequence into a new design decision inside spec.md
• for replacement or cleanup-discipline work, name known legacy surfaces and the expected remove/refactor/retain semantics before tasking begins
• for REST/API, generated contract, event payload, or material internal-interface work, record the behavior/contract delta and whether later system/integration design must run the triggered contract-design checkpoint
• for non-trivial custom implementation, new runtime dependencies, or meaningful helper/abstraction choices, record dependency/OSS due diligence before tasking begins
• for non-trivial architecture, system-design, workflow, integration, resilience, consistency, data-flow, or abstraction choices, record Pattern Fit Diligence before tasking begins or route to research/technical design when the pattern comparison is not ready

Boundaries

Do not:

• refine a raw product idea; use idea-refine
• perform engineering framing on an under-shaped request; use Phase 0 intake or spec-first-brainstorming
• absorb unresolved cross-domain design contradictions that belong in go-design-spec or specialist *-spec skills
• assemble a triggered split design/ bundle; that belongs to go-design-spec
• produce task breakdown, execution sequencing, or coder instructions; that belongs to planning-and-task-breakdown
• silently skip triggered technical design by smuggling split-design detail into spec.md; lean-local compact design answers are allowed when their trigger rationale is explicit
• mark lean-local spec.md review-ready without inline Risk Challenge, or mark full-orchestrated/protected-domain spec.md review-ready while the formal spec-clarification-challenge gate is unresolved or blocked
• copy BMAD, Spec Kit, Superpowers, or SDD templates directly into this repository's spec.md

Escalate When

Escalate if:

• the request is still idea-shaped, solution-led, missing its behavior delta, or lacks an accepted Phase 0 intake brief
• current external guidance materially affects the design and has not been researched yet
• the draft still contains unresolved domain contradictions that would make spec.md dishonest
• the clarification challenge returns blocks_spec_approval, blocks_specific_domain, or requires_user_decision items that the orchestrator has not reconciled
• the work is tiny enough that a separate spec pass would be ceremony instead of risk reduction
• non-trivial work still lacks a stable decisions record that go-design-spec can carry into design/ without reopening core framing

Core Defaults

• spec.md is the canonical decisions artifact.
• For lean-local work, the handoff path is spec.md with compact design answers, recorded subagent gate decision, and inline Risk Challenge -> specification review -> tasks.md.
• For full-orchestrated or protected-domain work, the handoff path is spec.md -> specification review -> system-integration-design -> go-code-ownership-design -> technical design review -> tasks.md, with compact design collapse only when explicitly justified, and formal spec-clarification-challenge is required before the spec is review-ready.
• For dedicated specification sessions, this pass ends at review-ready spec.md; specification review begins in a new session unless the task is direct-path and no spec.md is required.
• Use the repository's default section set unless merging sections makes the file clearer.
• Treat external frameworks as coverage prompts, not as headings to copy.
• Put stable decisions in spec.md, lean compact design answers in spec.md or one design/overview.md, split task-local technical context in design/ when triggered, execution order and task detail in tasks.md, and preserved evidence in research/*.md.
• Keep client-visible contract meaning explicit enough for review: spec.md owns the behavior/contract delta and final scope constraints, while triggered system-integration-design owns detailed contract shape in design/contracts/ or a compact-sufficient rationale before OpenAPI, handlers, generated clients, or tests are tasked.
• For replacement specs, record known old identifiers, routes, configs, commands, generated outputs, fixtures, docs, skills, agents, or mirrors and decide whether each is removed, refactored into the active path, or retained with owner, reason, proof, and exit condition.
• For dependency-sensitive specs, record selected and rejected stdlib, established repository-pattern, mature OSS, and custom-code options with current evidence. Missing dependency/OSS due diligence blocks review-readiness when the task would otherwise add a dependency, build custom infrastructure, or introduce a meaningful helper/abstraction.
• For pattern-sensitive specs, record selected and rejected design or system-design patterns with current source descriptions, real-use examples, task applicability, Go/repository fit, and custom-design justification when no known pattern fits. Missing Pattern Fit Diligence blocks review-readiness when the task would otherwise invent architecture, workflow, integration, resilience, consistency, data-flow, or abstraction shape.
• Prefer short explicit bullets over template sludge.
• Omit empty sections instead of padding the document for completeness theater.
• Deep coverage is good, but spec.md should close only the decisions needed before technical design. Later-domain consequences that do not require a new decision now should stay as constraints, proof obligations, or explicit no new decision required notes.

Context Intake (Dynamic Loading)

Rule: load the smallest sufficient set of artifacts. Do not bulk-load folders by default.

Always load:

• AGENTS.md
• docs/spec-first-workflow.md

Load by trigger:

• existing spec rewrite or continuation: the active spec.md
• triggered workflow control: the matching workflow-plan.md
• research-backed synthesis: the relevant research/*.md
• formal spec review-readiness: .agents/skills/spec-clarification-challenge/SKILL.md when full-orchestrated, high-risk, protected-domain, or otherwise triggered
• task-breakdown drift check: the matching tasks.md when it exists
• existing design bundle nearby: design/overview.md and only the smallest set of affected design artifacts needed to confirm ownership boundaries, not to author triggered split design in this pass

Conflict resolution:

• repository contract beats the reference file
• the more specific artifact beats generic guidance
• if a foreign template conflicts with repo artifact ownership, keep the repo model and translate the useful idea instead

Unknowns:

• if critical facts are missing, mark them as [assumption] or escalate

Reference Files Selector

References are compact rubrics and example banks, not exhaustive checklists. Load at most one reference by default after core context. Load more than one only when the task clearly spans independent decision pressures, such as both clarification-gate reconciliation and validation closeout.

Before loading a reference, use this behavior-change thesis test: "When loaded for symptom X, this file makes the model choose Y instead of likely mistake Z." If no row below matches that sentence, do not load a reference.

| Symptom | Behavior change | Load | |---|---|---| | Foreign-template pressure, framework vocabulary, or coverage gaps without a narrower symptom | Translate only behavior-changing coverage concerns into repo-native sections instead of copying PRD, BMAD, Spec Kit, Superpowers, or SDD headings | references/spec-patterns.md | | A spec is too thin, too bloated, or hard to size | Choose risk-proportional section depth instead of writing either "add X, test it" or a full PRD/design bundle | references/spec-section-depth-examples.md | | spec.md mixes final decisions with research, design detail, tasks, or transcripts | Move each fact to its owning artifact instead of using spec.md as an all-purpose dump | references/decision-placement-and-artifact-ownership.md | | The draft has TODO, TBD, blockers, soft assumptions, or user-only decisions | Label and route uncertainty by unblock path instead of inventing certainty or hiding blockers in Decisions | references/open-questions-and-assumptions.md | | A spec-clarification-challenge pass returned findings, or non-trivial spec review-readiness is questionable | Reconcile findings into final spec sections and gate status instead of pasting transcripts or marking review-ready through blockers | references/clarification-gate-reconciliation.md | | Validation language is vague, acceptance criteria need proof shaping, or Outcome is being written | Separate forward-looking proof obligations from evidence-backed outcome claims instead of writing "run tests" or "done" | references/validation-and-outcome-sections.md | | A non-trivial spec is at spec.md -> design/ handoff, or design detail leaks into the spec | Keep spec.md at behavior-decision level with explicit handoff and reopen conditions instead of stuffing component maps, sequences, ownership maps, or task lists into the spec | references/spec-handoff-to-design-checkpoints.md |

Neighboring-reference rule:

• For mixed-content cleanup, prefer decision-placement-and-artifact-ownership.md.
• For final handoff readiness or design leakage at review-readiness time, prefer spec-handoff-to-design-checkpoints.md.
• For foreign-template sprawl plus depth problems, prefer spec-section-depth-examples.md if the main decision is sizing; prefer spec-patterns.md if the main decision is translating framework concerns.
• Do not load a broad reference when a narrower row already matches the symptom.

Hard Skills

Mission

Make spec.md stable enough for mandatory specification review while preserving the repository's single-source-of-truth discipline.

Default Posture

• decision-first
• artifact-disciplined
• minimum sufficient structure
• no placeholder tolerance

Spec Shape Competency

• Start from the repository's default sections:
• Context
• Scope / Non-goals
• Constraints
• Decisions
• Open Questions / Assumptions
• Task Breakdown / Handoff Link
• Validation
• Outcome
• For lean-local specs, prefer the compact shape from docs/spec-first-workflow.md: Intent, Scope / Non-goals, Behavior / Contract Delta, Decisions, Dependency / OSS Due Diligence, Compact Design, Subagent Gate Decision, Risk Challenge, Task Handoff, Validation, and Outcome.
• Merge sections only when it makes the document clearer.
• Expand depth based on task risk and ambiguity, not on habit.

Coverage Competency

• Capture the behavior delta, affected actors, scope cuts, edge semantics, validation expectations, and material constraints.
• Capture dependency/OSS due diligence when relevant: current Go stdlib fit, established repo pattern fit, OSS candidates, maintenance/release activity, adoption such as stars or domain-equivalent signals, license, security posture, transitive dependency cost, API stability, repository-boundary fit, selected option, rejected options, and custom-code justification.
• Capture Pattern Fit Diligence when relevant: known candidate patterns, concise source descriptions, real-use examples, why the pattern forces match or do not match this task, Go/repository fit, selected pattern, rejected patterns, and custom-design justification.
• When the behavior delta replaces an old path, capture the legacy-surface delta explicitly: what old surfaces are gone, what is refactored into the active path, what remains intentionally retained, and what proof will make that claim auditable.
• Ask and answer before review-readiness: Does this change replace an existing path? If yes, list known old code, tests, fixtures, configs, docs, generated outputs, skills, agents, or mirrors. If no, record No known replacement surface.
• Use these external patterns only as coverage lenses:
• independently testable slices
• user journeys or demoable units
• measurable success criteria
• selective NFRs
• proof artifacts
• repository standards
• rejected alternatives when they materially affect planning
• If a pattern adds no execution value for this task, leave it out.

Artifact Ownership Competency

• Stable decisions belong in Decisions.
• Evidence history, comparisons, and raw external research belong in research/*.md.
• Research-backed decisions should link to the specific preserved research note or source surface when the provenance would help a later session trust or revisit the decision; keep the link short and do not copy the evidence narrative into Decisions.
• Task-local technical design context belongs in design/.
• Task sequencing and execution detail belong in tasks.md.
• Unresolved but visible gaps belong in Open Questions / Assumptions.
• Label Open Questions / Assumptions by unblock path when the uncertainty affects later sessions: [assumption] for bounded proceed-and-revisit assumptions, [accepted_risk] for deliberate risk with limits or proof obligations, [requires_user_decision] for external product or policy choices, [targeted_research] for repository evidence still needed, [defer_to_design] only for design-owned details after behavior is decided, and [reopen_spec_if_false] for downstream discoveries that would invalidate a spec-level assumption.
• Do not force go-design-spec or the planner to recover ownership, sequence, or execution order from spec.md when separate artifacts are warranted; for lean local, make those compact answers explicit in spec.md.

Technical-Design Handoff Competency

• A full-orchestrated or design-triggered spec must let go-design-spec derive the task-local design/ bundle without silently reopening core problem framing.
• A spec with REST/API, generated contract, event payload, or material internal-interface changes must name the contract-d

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dankosik
• Source: Dankosik/go-service-template-rest
• License: MIT

Install and usage instructions live in the source repository linked above.