vladm3105 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:
- Template (source of truth):
${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml - Layer README:
${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md - ID & tag standards:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md - Authoring style:
${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md - 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:
- Document Control · 2. Component Overview (description,
@adrdecision, language, dependencies) · 3. Interfaces (exports: signatures, types, errors) · - Data Models (typed fields, no SQL/ORM) · 5. Behavior (validation rules,
state transitions, error handling — each sourced from
@ears/@bdd) · - Implementation Notes (constraints, patterns, performance considerations) ·
- 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 dottedSPEC.NN.SS.xxxxelement 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-digitSPEC-NNN, numeric element-type-code tables, and the deleted SYS/REQ/CTR upstream layers.
Creation Process
- Read upstream — ADR decisions plus the BDD/EARS contracts the component satisfies.
- Reserve ID — next free
SPEC-NNunderdocs/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; seeframework/governance/ID_NAMING_STANDARDS.md§Cross-layer cardinality). - 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 indocs/06_SPEC/. - Document Control first, then complete all 8 sections from the template.
- Define interfaces and data models with typed signatures; specify
behavior with each rule sourced from
@ears/@bdd. - Add the required upstream tags (
@ears @bdd @adrper the necessary-upstream contract) and the downstream@tdd: TDD-NNcontract. - Update the SPEC index
docs/06_SPEC/SPEC-00_index.mdin the same change. - 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 @adrper necessary-upstream contract); downstream@tdd: TDD-NNcontract present. - Quantitative values use
@threshold:references (no magic numbers). - Diagram contract:
@diagram: c4-l3and@diagram: dfd-l3present (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 |