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:

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

Reference only existing documents in traceability tags

Use null only when upstream artifact type genuinely doesn't exist

NEVER use placeholders like BRD-XXX or TBD

Do NOT create missing upstream artifacts - skip functionality instead

Before creating TSPEC, read:

• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

• Upstream SPEC: Read technical specifications (PRIMARY SOURCE)

• Upstream REQ: Read atomic requirements

• 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

• 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)

Element Type Code Test Category Example

Unit Test Case 40 UTEST TSPEC.01.40.01

Integration Test Case 41 ITEST TSPEC.01.41.01

Smoke Test Case 42 STEST TSPEC.01.42.01

Functional Test Case 43 FTEST TSPEC.01.43.01

Performance Test Case 44 PTEST TSPEC.01.44.01

Security Test Case 45 SECTEST TSPEC.01.45.01

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

Type Code Abbreviation Purpose Primary Source

Unit Test 40 UTEST Individual function/method tests REQ (L7), SPEC (L9)

Integration Test 41 ITEST Component interaction tests CTR (L8), SYS (L6)

Smoke Test 42 STEST Post-deployment health checks EARS (L3), BDD (L4)

Functional Test 43 FTEST System behavior validation SYS (L6)

Performance Test 44 PTEST Load, stress, and response time testing SYS (L6), SPEC (L9)

Security Test 45 SECTEST Vulnerability and threat testing SYS (L6), ADR (L5)

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):

Item Details

Status Draft / Review / Approved / Implemented

Version 0.1.0

Date Created YYYY-MM-DD

Last Updated YYYY-MM-DD

Author [Author name]

Component [Component/module name]

SPEC Reference SPEC-NN

Coverage Target XX%

TASKS-Ready Score [XX]% (Target: see type-specific)

Core Sections:

• Document Control: Metadata and version tracking

• Test Scope: Component under test, categories, dependencies

• Test Case Index: Summary table of all test cases

• Test Case Details: Full specification per test case

• Coverage Matrix: REQ/SPEC coverage tracking

• 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:

Pseudocode:

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

Error Cases:

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

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

Artifact Element Type Code Example

BRD Business Requirement 01 BRD.01.01.03

PRD Product Feature 07 PRD.01.07.02

EARS EARS Statement 25 EARS.01.25.01

BDD Scenario 14 BDD.01.14.01

ADR Document reference

ADR-033 (dash notation)

SYS System Requirement 26 SYS.01.26.01

REQ Atomic Requirement 27 REQ.01.27.01

SPEC Document reference

SPEC-01 (dash notation)

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:

Notation Format Artifacts Purpose

Dash TYPE-NN ADR, SPEC, CTR Technical artifacts - references to files/documents

Dot TYPE.NN.TT.SS BRD, PRD, EARS, BDD, SYS, REQ, TSPEC Hierarchical artifacts - references to elements inside documents

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)

Check Description

CHECK 1 Filename format valid ({TYPE}-NN_{slug}.md)

CHECK 2 YAML frontmatter present with required fields

CHECK 3 Document Control table complete

CHECK 4 All required sections present

CHECK 5 Element ID format compliance (TSPEC.NN.TT.SS)

CHECK 6 Element type code matches document type (40/41/42/43)

CHECK 7 All 8 required traceability tags present

CHECK 8 Parent SPEC reference valid and file exists

Tier 2: Warnings

Check Description

CHECK W1 I/O table present for each test case

CHECK W2 Pseudocode provided for complex tests

CHECK W3 Coverage matrix complete

CHECK W4 TASKS-Ready Score meets type-specific target

CHECK W5 Error cases documented

Tier 3: Info

Check Description

CHECK I1 Test fixtures documented

CHECK I2 Mock strategy specified

CHECK I3 Performance targets defined (FTEST)

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

• Wrong element type code: Use 40 for UTEST, 41 for ITEST, 42 for STEST, 43 for FTEST

• Missing I/O tables: Every test case needs input/output specification

• No coverage matrix: Must track REQ element coverage

• Wrong tag format: Use TSPEC.NN.TT.SS for elements, TYPE-NN for documents

• Missing cumulative tags: Layer 10 requires all 8-9 upstream tags

• Legacy test IDs: Use TSPEC.NN.TT.SS, NOT TC-XXX, UT-XXX, etc.

• No pseudocode: Complex tests require algorithm specification

• 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

This Layer Required Upstream Tags Count

TSPEC (Layer 10) @brd, @prd, @ears, @bdd, @adr, @sys, @req, @spec (+ @ctr if created) 8-9 tags

Auto-Fix Actions (No Confirmation Required)

Issue Fix Action

Missing upstream tag Add with upstream document reference

Invalid tag format Correct to TYPE.NN.TT.SS (4-segment) or TYPE-NN format

Broken link Recalculate path from current location

Missing traceability section Insert from template

Validation Codes Reference

Code Description Severity

XDOC-001 Referenced requirement ID not found ERROR

XDOC-002 Missing cumulative tag ERROR

XDOC-003 Upstream document not found ERROR

XDOC-006 Tag format invalid ERROR

XDOC-007 Gap in cumulative tag chain ERROR

XDOC-009 Missing traceability section ERROR

TSPEC v2.0 Validation Infrastructure (2026-03-06)

Overview

TSPEC validation infrastructure provides automated quality gates, pre-commit hooks, and type-specific validators for all 6 test types (UTEST, ITEST, STEST, FTEST, PTEST, SECTEST).

Features:

• Pre-commit hooks for automatic validation

• Standardized error codes (38 TSPEC-specific codes)

• Schema validation with flexible path resolution

• JSON output for automation

• Enhanced batch validator with CLI options

• Type-specific quality gates and thresholds

Type-Specific Validators

Test Type Validator Threshold Description

UTEST validate_utest.py

≥90% Unit test coverage of REQ elements

ITEST validate_itest.py

≥90% Contract coverage and sequence diagrams

STEST validate_stest.py

100% Critical path smoke tests (strict)

FTEST validate_ftest.py

≥90% SYS requirement coverage

PTEST validate_ptest.py

≥85% Performance scenario coverage

SECTEST validate_sectest.py

≥90% Security threat and control coverage

Pre-Commit Hooks

Automatic validation on every commit:

.pre-commit-config.yaml (auto-configured)

• id: tspec-core-validator name: Validate TSPEC core checks entry: bash ai_dev_ssd_flow/10_TSPEC/scripts/tspec_core_validator_hook.sh

• id: tspec-quality-gate name: Validate TSPEC quality gates entry: bash ai_dev_ssd_flow/10_TSPEC/scripts/tspec_quality_gate_hook.sh

• id: tspec-tasks-ready name: Validate TSPEC TASKS-Ready scores entry: bash ai_dev_ssd_flow/10_TSPEC/scripts/tspec_tasks_ready_hook.sh

Exit codes:

• 0 = PASS (all checks passed)

• 1 = WARN (warnings only, commit allowed)

• 2 = FAIL (errors present, commit blocked)

Error Code Format

Pattern: [CODE] Message (context)

Examples:

[UTEST-E002] Missing I/O table (TC-001) [TSPEC-E007] Missing Traceability section (missing @spec reference) [ITEST-E001] CTR coverage 75.0% < 90%

Error Code Categories:

Prefix Category Count Examples

TSPEC-E Generic errors 10 Missing sections, invalid format

UTEST-E/W Unit test issues 7 Low REQ coverage, missing pseudocode

ITEST-E/W Integration issues 4 Missing sequence diagrams, weak coverage

STEST-E Smoke test issues 4 Timeout exceeded, missing rollback

FTEST-E/W Functional issues 3 Low SYS coverage, missing thresholds

PTEST-E/W Performance issues 4 Missing load scenarios, invalid metrics

SECTEST-E/W Security issues 4 Missing threat scenarios, weak controls

Batch Validation

Enhanced validator with 6 CLI options:

Basic validation

bash ai_dev_ssd_flow/10_TSPEC/scripts/validate_all_tspec_enhanced.sh docs/10_TSPEC

Verbose output with quality gates

bash ai_dev_ssd_flow/10_TSPEC/scripts/validate_all_tspec_enhanced.sh --verbose docs/10_TSPEC

JSON output for automation

bash ai_dev_ssd_flow/10_TSPEC/scripts/validate_all_tspec_enhanced.sh --json docs/10_TSPEC

Force color output

bash ai_dev_ssd_flow/10_TSPEC/scripts/validate_all_tspec_enhanced.sh --color docs/10_TSPEC

Options:

• --verbose : Show detailed quality gate breakdown

• --quality-gates : Show quality scores per gate

• --json : Machine-readable JSON output

• --color : Force color output

• --no-color : Disable color output

• --help : Show usage information

Individual Type Validation

Validate specific test type:

Unit tests

python3 ai_dev_ssd_flow/10_TSPEC/scripts/validate_utest.py docs/10_TSPEC/UTEST/*.md

Integration tests

python3 ai_dev_ssd_flow/10_TSPEC/scripts/validate_itest.py docs/10_TSPEC/ITEST/*.md -v

With quality gates

python3 ai_dev_ssd_flow/10_TSPEC/scripts/validate_ftest.py --quality-gates docs/10_TSPEC/FTEST/*.md

Schema Validation

Flexible path resolution (4+ strategies):

• Sibling to TSPEC file: UTEST/UTEST_MVP_SCHEMA.yaml

• Parent directory: 10_TSPEC/UTEST/UTEST_MVP_SCHEMA.yaml

• Search upward to TSPEC or 10_TSPEC directory

• Graceful degradation if schema not found

YAML frontmatter validation:

• Required fields: id , title , version , cumulative_tags , test_type

• Type-specific fields validated per test type

• Schema errors block document creation

Quality Score Calculation

Combined score across all 6 test types:

Calculate quality score

bash ai_dev_ssd_flow/10_TSPEC/scripts/validate_tspec_quality_score.sh docs/10_TSPEC

Output:

UTEST: 92.5% ITEST: 88.0% STEST: 100.0% FTEST: 91.2% PTEST: 86.0% SECTEST: 90.5%

Combined: 91.4% Status: [PASS] Quality score ≥85%

Test Fixtures

42 test fixtures for regression testing:

Create test fixtures (if needed)

bash ai_dev_ssd_flow/10_TSPEC/scripts/create_test_fixtures.sh

Categories:

• Valid documents (6 types × 3 variants = 18 fixtures)

• Missing sections (6 types = 6 fixtures)

• Invalid traceability (6 types = 6 fixtures)

• Schema violations (6 types = 6 fixtures)

• Edge cases (6 additional fixtures)

File Exclusion Patterns

Auto-excluded from validation:

Pattern Purpose Example

-00_

Reserved IDs UTEST-00_template.md

TEMPLATE

Template files UTEST-MVP-TEMPLATE.md

FIX_PLAN

Fix plans UTEST-01_FIX_PLAN.md

.A_audit_report

Audit reports UTEST-01.A_audit_report.md

.R_review_report

Review reports UTEST-01.R_review_report.md

.F_fix_report

Fix reports UTEST-01.F_fix_report.md

.V_validation_report

Validation reports UTEST-01.V_validation_report.md

Integration with /doc-tspec-audit

Unified audit workflow (recommended):

Run complete audit (validator + reviewer)

/doc-tspec-audit

Produces: TSPEC-NN.A_audit_report.md with:

- Schema validation results

- Quality gate scores

- Error code details

- Recommended fixes

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

Version Date Changes

2.0 2026-03-06 MAJOR: Added v2.0 validation infrastructure with pre-commit hooks (3 hooks), error codes (38 TSPEC-specific codes), schema validation, enhanced batch validator (6 CLI options), error code integration in all 6 validators (UTEST/ITEST/STEST/FTEST/PTEST/SECTEST), 42 test fixtures, JSON output, quality score calculation, and comprehensive validation documentation

1.2 2026-02-27 Normalized frontmatter to metadata schema with versioning_policy ; aligned cross-document/tag validation command examples to canonical ai_dev_ssd_flow/scripts/* locations

1.1 2026-02-26 Added PTEST (code 44) and SECTEST (code 45) support; Fixed template paths to ai_dev_ssd_flow/10_TSPEC/

1.0 2026-02-08 Initial release with UTEST/ITEST/STEST/FTEST support (codes 40-43)