doc-tspec

Purpose

Create Test Specifications (TSPEC) – Layer 10 artifact in the SDD workflow that defines test cases for Test-Driven Development (TDD) between SPEC (Layer 9) and TASKS (Layer 11).

Layer: 10

Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5), SYS (Layer 6), REQ (Layer 7), CTR (Layer 8), SPEC (Layer 9)

Downstream Artifacts: TASKS (Layer 11), Code (Layer 12)

Prerequisites

Upstream Artifact Verification (CRITICAL)

Before creating this document, you MUST:

1. List existing upstream artifacts:

   ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ docs/05_ADR/ docs/06_SYS/ docs/07_REQ/ docs/08_CTR/ docs/09_SPEC/ 2>/dev/null
   

2. Reference only existing documents in traceability tags

3. Use null only when upstream artifact type genuinely doesn’t exist

4. NEVER use placeholders like BRD-XXX or TBD

5. Do NOT create missing upstream artifacts – skip functionality instead

Before creating TSPEC, read:

1. Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
2. Upstream SPEC: Read technical specifications (PRIMARY SOURCE)
3. Upstream REQ: Read atomic requirements
4. Template by Type:
   • UTEST: ai_dev_ssd_flow/10_TSPEC/UTEST/UTEST-MVP-TEMPLATE.md
   • ITEST: ai_dev_ssd_flow/10_TSPEC/ITEST/ITEST-MVP-TEMPLATE.md
   • STEST: ai_dev_ssd_flow/10_TSPEC/STEST/STEST-MVP-TEMPLATE.md
   • FTEST: ai_dev_ssd_flow/10_TSPEC/FTEST/FTEST-MVP-TEMPLATE.md
5. TSPEC README: ai_dev_ssd_flow/10_TSPEC/README.md

When to Use This Skill

Use doc-tspec when:

• Have completed BRD through SPEC (Layers 1-9)
• Ready to define test cases before implementation
• Following Test-Driven Development workflow
• Need to specify unit, integration, smoke, or functional tests
• You are at Layer 10 of the SDD workflow

Reserved ID Exemption (TSPEC-00_*)

Scope: Documents with reserved ID 000 are FULLY EXEMPT from validation.

Pattern: TSPEC-00_*.md, {TYPE}-00_*.md (where TYPE is UTEST/ITEST/STEST/FTEST)

Document Types:

• Index documents (TSPEC-00_index.md)
• Traceability matrix templates (TSPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md)
• Glossaries, registries, checklists

Rationale: Reserved ID 000 documents are framework infrastructure (indexes, templates, reference materials), not project artifacts requiring traceability or quality gates.

Validation Behavior: Skip all checks when filename matches TSPEC-00_* or {TYPE}-00_* pattern.

Element ID Format (MANDATORY)

Pattern: TSPEC.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)

REMOVED PATTERNS – Do NOT use legacy formats:

• TC-XXX – Use TSPEC.NN.TT.SS instead
• UT-XXX – Use TSPEC.NN.40.SS instead
• IT-XXX – Use TSPEC.NN.41.SS instead
• ST-XXX – Use TSPEC.NN.42.SS instead
• FT-XXX – Use TSPEC.NN.43.SS instead

Reference: doc-naming skill for complete element type codes.

TSPEC Types Overview

Note: Acceptance tests remain in BDD (Layer 4), not duplicated in TSPEC.

TSPEC-Specific Guidance

1. Test Document Structure

Directory Structure:

docs/10_TSPEC/
├── UTEST/
│   ├── UTEST-01_{component}_unit.md
│   └── UTEST-02_{component}_unit.md
├── ITEST/
│   ├── ITEST-01_{component}_integration.md
│   └── ITEST-02_{component}_integration.md
├── STEST/
│   ├── STEST-01_{component}_smoke.md
│   └── STEST-02_{component}_smoke.md
├── FTEST/
│   ├── FTEST-01_{component}_functional.md
│   └── FTEST-02_{component}_functional.md
└── TSPEC-00_TRACEABILITY_MATRIX.md

2. Required Sections (All TSPEC Types)

Document Control (MANDATORY – First section):

Core Sections:

1. Document Control: Metadata and version tracking
2. Test Scope: Component under test, categories, dependencies
3. Test Case Index: Summary table of all test cases
4. Test Case Details: Full specification per test case
5. Coverage Matrix: REQ/SPEC coverage tracking
6. Traceability: Cumulative upstream/downstream tags

3. Test Case Format

Each test case MUST include:

### TSPEC.NN.TT.SS: [Test Name]

**Category**: [Logic] | [State] | [Validation] | [Edge] | [Integration] | [Critical Path]

**Traceability**:
- @req: REQ.NN.27.XX
- @spec: SPEC-NN (Section X.Y)

**Input/Output Table**:

| Input | Expected Output | Notes |
|-------|-----------------|-------|
| `param1="valid"` | `True` | Happy path |
| `param1=""` | `ValidationError` | Empty input |

**Pseudocode**:

GIVEN valid input parameters WHEN function_under_test(param1) is called THEN result equals expected_output AND no side effects occur

**Error Cases**:

| Error Condition | Expected Behavior |
|-----------------|-------------------|
| Invalid input type | Raise `TypeError` |

4. Type-Specific Requirements

UTEST (Unit Tests – Code 40)

TASKS-Ready Score Target: >=90%

Required Tags: @req, @spec

Test Categories: [Logic], [State], [Validation], [Edge]

Coverage Requirements:

• Function coverage: >=90%
• Branch coverage: >=80%
• REQ element coverage: >=90%

ITEST (Integration Tests – Code 41)

TASKS-Ready Score Target: >=90%

Required Tags: @ctr, @sys, @spec

Test Categories: [Integration], [Contract], [Sequence]

Requirements:

• Sequence diagrams for complex interactions
• CTR contract validation
• Mock/stub strategy documented

STEST (Smoke Tests – Code 42)

TASKS-Ready Score Target: 100%

Required Tags: @ears, @bdd, @req

Test Categories: [Critical Path], [Health Check], [Deployment]

Requirements:

• Total execution time <5 minutes
• Rollback procedures documented
• Critical path coverage 100%

FTEST (Functional Tests – Code 43)

TASKS-Ready Score Target: >=90%

Required Tags: @sys, @threshold

Test Categories: [Functional], [Scenario], [End-to-End]

Requirements:

• SYS requirement coverage
• Threshold registry references for performance assertions

5. Coverage Matrix Format

## Coverage Matrix

| REQ ID | REQ Title | Test IDs | Coverage |
|--------|-----------|----------|----------|
| REQ.NN.27.01 | [Title] | TSPEC.NN.40.01, TSPEC.NN.40.03 | Covered |
| REQ.NN.27.02 | [Title] | TSPEC.NN.40.02 | Covered |
| REQ.NN.27.03 | [Title] | - | NOT COVERED |

**Coverage Summary**:
- Total REQ elements: [N]
- Covered: [N]
- Coverage: [XX]%

Cumulative Tagging Requirements

Layer 10 (TSPEC): Must include tags from Layers 1-9

Tag Count: 8 required tags (minimum), 9 if CTR created

Element Type Codes for Cumulative Tags

Minimum (8 tags – CTR skipped):

## Traceability

**Required Tags** (Cumulative Tagging Hierarchy - Layer 10):

@brd: BRD.01.01.03
@prd: PRD.01.07.02
@ears: EARS.01.25.01
@bdd: BDD.01.14.01
@adr: ADR-033, ADR-045
@sys: SYS.01.26.01
@req: REQ.01.27.01
@spec: SPEC-01

Maximum (9 tags – CTR included):

@brd: BRD.01.01.03
@prd: PRD.01.07.02
@ears: EARS.01.25.01
@bdd: BDD.01.14.01
@adr: ADR-033, ADR-045
@sys: SYS.01.26.01
@req: REQ.01.27.01
@ctr: CTR-01
@spec: SPEC-01

Tag Format Convention (By Design)

The SDD framework uses two distinct notation systems for cross-references:

Key Distinction:

• @adr: ADR-033 – Points to the document ADR-033_risk_limit_enforcement.md
• @brd: BRD.17.01.01 – Points to element 01.01 inside document BRD-017.md

Validation Checks

Tier 1: Errors (Blocking)

Tier 2: Warnings

Tier 3: Info

Creation Process

Step 1: Identify Test Type Needed

Determine which TSPEC type(s) to create based on requirements:

• UTEST for unit testing individual functions
• ITEST for component integration testing
• STEST for deployment health verification
• FTEST for system behavior validation

Step 2: Read Upstream Artifacts

Focus on SPEC (Layer 9) and REQ (Layer 7) as primary sources.

Step 3: Reserve ID Number

Check docs/10_TSPEC/{TYPE}/ for next available ID number.

ID Numbering Convention: Start with 2 digits and expand only as needed.

• Correct: UTEST-01, ITEST-02, STEST-99
• Incorrect: UTEST-001, ITEST-009 (extra leading zero not required)

Step 4: Create TSPEC File

File naming: docs/10_TSPEC/{TYPE}/{TYPE}-NN_{slug}.md

Examples:

• docs/10_TSPEC/UTEST/UTEST-01_auth_service_unit.md
• docs/10_TSPEC/ITEST/ITEST-01_api_integration.md
• docs/10_TSPEC/STEST/STEST-01_deployment_smoke.md
• docs/10_TSPEC/FTEST/FTEST-01_order_processing_functional.md

Step 5: Fill Document Control Section

Complete metadata including SPEC Reference and TASKS-Ready Score.

Step 6: Define Test Scope

Document component under test, test categories, and dependencies.

Step 7: Create Test Case Index

Summary table listing all test cases with priority.

Step 8: Write Test Case Details

For each test case:

• Assign Element ID (TSPEC.NN.TT.SS)
• Define category
• Add traceability tags
• Create I/O table
• Write pseudocode
• Document error cases

Step 9: Build Coverage Matrix

Map test cases to REQ elements, calculate coverage percentage.

Step 10: Add Cumulative Tags

Include all 8-9 upstream tags (@brd through @spec).

Step 11: Create/Update Traceability Matrix

MANDATORY: Update docs/10_TSPEC/TSPEC-00_TRACEABILITY_MATRIX.md

Step 12: Validate TSPEC

# Type-specific validation
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_utest.py docs/10_TSPEC/UTEST/UTEST-01_*.md
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_itest.py docs/10_TSPEC/ITEST/ITEST-01_*.md
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_stest.py docs/10_TSPEC/STEST/STEST-01_*.md
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_ftest.py docs/10_TSPEC/FTEST/FTEST-01_*.md

# Combined quality score
bash ai_dev_ssd_flow/10_TSPEC/scripts/validate_tspec_quality_score.sh docs/10_TSPEC/

# Cumulative tagging validation
python ai_dev_ssd_flow/scripts/validate_tags_against_docs.py \
  --artifact UTEST-01 \
  --expected-layers brd,prd,ears,bdd,adr,sys,req,spec \
  --strict

Step 13: Commit Changes

Commit TSPEC file and traceability matrix.

Validation

Automated Validation

# All TSPEC types
bash ai_dev_ssd_flow/10_TSPEC/scripts/validate_all_tspec.sh docs/10_TSPEC/

# Type-specific validation
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_utest.py docs/10_TSPEC/UTEST/*.md
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_itest.py docs/10_TSPEC/ITEST/*.md
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_stest.py docs/10_TSPEC/STEST/*.md
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_ftest.py docs/10_TSPEC/FTEST/*.md

# Cross-document validation
python ai_dev_ssd_flow/scripts/validate_cross_document.py --document docs/10_TSPEC/UTEST/UTEST-01_*.md

Manual Checklist

• Document Control section at top
• Test Scope defines component and categories
• Test Case Index lists all tests with priority
• Each test case has TSPEC.NN.TT.SS ID
• Element type code matches document type (40/41/42/43)
• I/O tables present for all test cases
• Pseudocode provided for complex logic
• Error cases documented
• Coverage Matrix complete
• TASKS-Ready Score meets type-specific target
• Cumulative tags: @brd through @spec (8-9 tags)
• Traceability matrix updated

Diagram Standards

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See: ai_dev_ssd_flow/DIAGRAM_STANDARDS.md and mermaid-gen skill.

Common Pitfalls

1. Wrong element type code: Use 40 for UTEST, 41 for ITEST, 42 for STEST, 43 for FTEST
2. Missing I/O tables: Every test case needs input/output specification
3. No coverage matrix: Must track REQ element coverage
4. Wrong tag format: Use TSPEC.NN.TT.SS for elements, TYPE-NN for documents
5. Missing cumulative tags: Layer 10 requires all 8-9 upstream tags
6. Legacy test IDs: Use TSPEC.NN.TT.SS, NOT TC-XXX, UT-XXX, etc.
7. No pseudocode: Complex tests require algorithm specification
8. Incomplete error cases: Document expected behavior for all error conditions

Post-Creation Validation (MANDATORY – NO CONFIRMATION)

CRITICAL: Execute this validation loop IMMEDIATELY after document creation. Do NOT proceed to next document until validation passes.

Automatic Validation Loop

LOOP:
  1. Run: python ai_dev_ssd_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed

Validation Command

# Per-document validation (Phase 1)
python ai_dev_ssd_flow/scripts/validate_cross_document.py --document docs/10_TSPEC/UTEST/UTEST-NN_slug.md --auto-fix

# Layer validation (Phase 2) - run when all TSPEC documents complete
python ai_dev_ssd_flow/scripts/validate_cross_document.py --layer TSPEC --auto-fix

Layer-Specific Upstream Requirements

Auto-Fix Actions (No Confirmation Required)

Validation Codes Reference

Quality Gate

Blocking: YES – Cannot proceed to next document until Phase 1 validation passes with 0 errors.

Next Skill

After creating TSPEC, use:

doc-tasks – Create Task Breakdown (Layer 11)

The TASKS will:

• Reference this TSPEC for test implementation
• Include all 9-10 upstream tags
• Break SPEC and TSPEC into actionable tasks
• Provide AI-structured TODO format

Reference Documents

TSPEC artifacts do not support REF documents. Reference documents are limited to BRD and ADR types only per the SDD framework.

For supplementary documentation needs, create:

• BRD-REF: Business context documentation
• ADR-REF: Test strategy guides, coverage analysis reports

Related Resources

• Templates:
  • ai_dev_ssd_flow/10_TSPEC/UTEST/UTEST-MVP-TEMPLATE.md
  • ai_dev_ssd_flow/10_TSPEC/ITEST/ITEST-MVP-TEMPLATE.md
  • ai_dev_ssd_flow/10_TSPEC/STEST/STEST-MVP-TEMPLATE.md
  • ai_dev_ssd_flow/10_TSPEC/FTEST/FTEST-MVP-TEMPLATE.md
• TSPEC README: ai_dev_ssd_flow/10_TSPEC/README.md
• TSPEC Index: ai_dev_ssd_flow/10_TSPEC/TSPEC-00_index.md
• Traceability Matrix Template: ai_dev_ssd_flow/10_TSPEC/TSPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
• doc-naming skill: .claude/skills/doc-naming/SKILL.md (element type codes)
• doc-spec skill: .claude/skills/doc-spec/SKILL.md (upstream SPEC creation)
• quality-advisor skill: .claude/skills/quality-advisor/SKILL.md (quality guidance)

Quick Reference

TSPEC Purpose: Test specifications for TDD workflow

Layer: 10

Element ID Format: TSPEC.NN.TT.SS

• Unit Test = 40
• Integration Test = 41
• Smoke Test = 42
• Functional Test = 43

Removed Patterns: TC-XXX, UT-XXX, IT-XXX, ST-XXX, FT-XXX

Tags Required: @brd through @spec (8-9 tags)

Format: Markdown with I/O tables and pseudocode

TSPEC Types:

• UTEST: Unit tests (>=90% coverage, REQ-focused)
• ITEST: Integration tests (>=85% coverage, CTR-focused)
• STEST: Smoke tests (100% critical paths, <5min execution)
• FTEST: Functional tests (>=85% SYS coverage)

Key Sections:

• Document Control
• Test Scope (component, categories, dependencies)
• Test Case Index
• Test Case Details (I/O tables, pseudocode, error cases)
• Coverage Matrix
• Traceability (cumulative tags)

Quality Gate: Type-specific TASKS-Ready Score

Next: doc-tasks

Version History