doc-spec

doc-spec

Purpose

Create a Technical Specification (SPEC) — Layer 6 of the SDD flow. A SPEC is the implementation-ready, C4-L3 (Component) contract for a single software component: its interfaces, data models, and behavior — written before any downstream test or code.

Layer: 6 — the unified specification. A SPEC subsumes what older revisions split into component/data/ux/risk/process specs; there is now one SPEC artifact per component. Upstream: EARS, BDD, ADR (per the necessary-upstream contract; ADR is the primary source. Upstream PRD/BRD lineage is reachable transitively via the @-tag chain). Downstream: TDD → IPLAN → Code.

When to Use

Use doc-spec when:

• Architecture decisions (ADR) are settled and you need to specify a component.
• Turning EARS/BDD acceptance contracts into concrete interfaces, data models, and behavior rules.
• You need an implementation-ready contract before writing TDD test cases.

For end-to-end generation from BDD/ADR, a prompt, or an IPLAN, use ../doc-spec-autopilot/SKILL.md.

Prerequisites

SPEC sits at Layer 6, so verify the required upstream artifacts (EARS, BDD, ADR) exist before writing. Reference only documents that already exist; never invent placeholders like SPEC-XXX or ADR-XXX. Before writing, read:

1. Template (source of truth): ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
2. Layer README: ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md
3. ID & tag standards: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
4. Authoring style: ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
5. Upstream ADR (primary) plus the BDD/EARS acceptance contracts the component must satisfy.

Confirm existing upstream artifacts and no ID collision: ls docs/05_ADR/ docs/06_SPEC/ 2>/dev/null.

Layer Guidance

C4-L3 scope (stay at the component level)

SPEC is the Component level. Describe component interfaces and contracts, not architecture decisions (ADR) or source code (Code).

Stay here (PASS)	Out of scope (FAIL)
AuthService, UserRepository, NotificationQueue	auth_service.py, async def validate_token()
interface signatures, typed data models	concrete SQL tables, Redis key formats
behavior rules, state transitions, error contracts	Kubernetes pod configs, deployment manifests

Required diagram tags: @diagram: c4-l3, @diagram: dfd-l3 (use ../charts-flow/SKILL.md). Sequence diagrams must include alt/else for error paths; never embed C4-L4 code/class diagrams.

Required structure (8 sections)

document_control comes first (status, version, date, author, component, tdd_ready_score). Then:

1. Document Control · 2. Component Overview (description, @adr decision, language, dependencies) · 3. Interfaces (exports: signatures, types, errors) ·
2. Data Models (typed fields, no SQL/ORM) · 5. Behavior (validation rules, state transitions, error handling — each sourced from @ears/@bdd) ·
3. Implementation Notes (constraints, patterns, performance considerations) ·
4. Downstream TDD Contracts (@tdd: TDD-NN, test-file map) · 8. Traceability.

See SPEC-TEMPLATE.yaml for per-section content. Format is YAML.

Element IDs and tags

• SPEC is a DOCUMENT-level artifact — reference it in dash form SPEC-NN (two digits, no extra leading zero: SPEC-01, SPEC-99, SPEC-102). Downstream artifacts tag it @spec: SPEC-12. There is no dotted SPEC.NN.SS.xxxx element form for SPEC itself.
• Required upstream tags (per the necessary-upstream contract): hierarchical refs use the 4-segment element form — @ears: EARS.NN.SS.xxxx, @bdd: BDD.NN.SS.xxxx; document-level @adr: ADR-NN. Upstream PRD/BRD lineage is reachable transitively via the EARS/BDD @-tag chain — do not emit @brd:/@prd: on SPEC elements.
• Thresholds: never hardcode performance/timeout/rate-limit values — use @threshold: registry references.
• Removed patterns (do not use): STEP-XXX, IF-XXX, INT-XXX, DM-XXX, MODEL-XXX, VR-XXX, 3-digit SPEC-NNN, numeric element-type-code tables, and the deleted SYS/REQ/CTR upstream layers.

Creation Process

1. Read upstream — ADR decisions plus the BDD/EARS contracts the component satisfies.
2. Reserve ID — next free SPEC-NN under docs/06_SPEC/. Per-layer independence (CLEANUP-PR-F item 18): pick the next-free number in YOUR layer's index — the upstream's number is NOT your number (doc numbers are per-layer sequential and independent; see framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality).
3. Create the nested folder — every SPEC lives in docs/06_SPEC/SPEC-NN_{slug}/SPEC-NN_{slug}.yaml, regardless of size. Never place a SPEC file directly in docs/06_SPEC/.
4. Document Control first, then complete all 8 sections from the template.
5. Define interfaces and data models with typed signatures; specify behavior with each rule sourced from @ears/@bdd.
6. Add the required upstream tags (@ears @bdd @adr per the necessary-upstream contract) and the downstream @tdd: TDD-NN contract.
7. Update the SPEC index docs/06_SPEC/SPEC-00_index.md in the same change.
8. Validate (below) and commit the SPEC and index together.

Validation

This skill is the validator (no runtime code). Apply against ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md and ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md.

• YAML parses; Document Control is the first section.
• All 8 sections present and non-empty; format is YAML (not markdown).
• Component-level only (no code/SQL/deployment detail; C4-L3 scope holds).
• Document ID is dash form SPEC-NN; no dotted SPEC element IDs; no removed patterns.
• Required upstream tags present (@ears @bdd @adr per necessary-upstream contract); downstream @tdd: TDD-NN contract present.
• Quantitative values use @threshold: references (no magic numbers).
• Diagram contract: @diagram: c4-l3 and @diagram: dfd-l3 present (use ../charts-flow/SKILL.md).
• Traceability matrix / index created or updated; no broken links.

Code	Meaning	Severity
XDOC-006	Tag format invalid	error
XDOC-007	Missing required upstream tag	error
XDOC-008	Broken internal link	error
XDOC-009	Missing traceability section	error

Quality gate (blocking): TDD-Ready score ≥ 90/100 before moving on. If issues are found, fix and re-check; if unfixable, log for manual review.

Next Skill

../doc-tdd/SKILL.md — the TDD references this SPEC (@spec: SPEC-NN) along with its own required @ears @bdd @adr upstream tags, and defines test cases, inputs, expected outputs, and thresholds for the SPEC contracts.

Adaptation

Read .aidoc/profile.yaml; honor only this skill's knobs (section_toggles, glossary). Ignore unknown keys; absent a profile, use framework defaults. Authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md.

Related Resources

• Template / authoring rules: ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
• Layer README: ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md
• Index template: ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-00_index.TEMPLATE.md
• ID & tag standards: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
• Upstream decisions: ../doc-adr/SKILL.md · Downstream tests: ../doc-tdd/SKILL.md
• Quality gate: ../doc-spec-audit/SKILL.md · Fixes: ../doc-spec-fixer/SKILL.md
• Generation pipeline: ../doc-spec-autopilot/SKILL.md

Quick Reference

Purpose	Specify a component: interfaces, data models, behavior
Layer	6 (C4-L3 Component)
Upstream tags	@ears @bdd @adr (per necessary-upstream contract)
Document ID	Dash form SPEC-NN (document-level; no dotted element IDs)
Must include	Document Control (first), 8 sections, @threshold for numbers
Format	YAML
Next	doc-tdd