home / skills / vladm3105 / aidoc-flow-framework / doc-tspec

doc-tspec skill

Q: What ID format must each test case use?

Use TSPEC.NN.TT.SS where TT is 40/41/42/43 for UTEST/ITEST/STEST/FTEST respectively.

Q: What traceability tags are mandatory?

Include cumulative tags from Layers 1–9: @brd, @prd, @ears, @bdd, @adr, @sys, @req, @spec (add @ctr if CTR exists).

Q: Can I use placeholders for missing upstream docs?

No. Reference only existing documents; use null only if the artifact genuinely does not exist and skip related tests if necessary.

Q: Are there automated checks?

Yes. Use the provided type-specific validation scripts and the combined quality score scripts to run Tier 1 errors, warnings, and info checks.

safe

/.claude/skills/doc-tspec

This skill helps you create Layer 10 TSPEC documents by integrating upstream artifacts, templates, and traceability for robust unit, integration, smoke, and

npx playbooks add skill vladm3105/aidoc-flow-framework --skill doc-tspec

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

20.1 KB

---
name: doc-tspec
description: Create Test Specifications (TSPEC) - Layer 10 artifact for unit, integration, smoke, and functional test cases
tags:
  - sdd-workflow
  - layer-10-artifact
  - shared-architecture
custom_fields:
  layer: 10
  artifact_type: TSPEC
  architecture_approaches: [ai-agent-based, traditional-8layer]
  priority: shared
  development_status: active
  skill_category: core-workflow
  upstream_artifacts: [BRD, PRD, EARS, BDD, ADR, SYS, REQ, CTR, SPEC]
  downstream_artifacts: [TASKS, Code]
  version: "1.1"
  last_updated: "2026-02-26T00:00:00"
---

# 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**:
   ```bash
   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)

| 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](../.claude/skills/doc-naming/SKILL.md) 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**:
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:

```markdown
### 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

```markdown
## 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

| 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)**:
```markdown
## 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)**:
```markdown
@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

```bash
# 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_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

```bash
# 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_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_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

```bash
# Per-document validation (Phase 1)
python ai_dev_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_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 |

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

Overview

This skill creates Test Specifications (TSPEC) as Layer 10 artifacts to define unit, integration, smoke, and functional test cases for Test-Driven Development. It enforces element ID formats, traceability to upstream artifacts, and type-specific coverage and readiness targets. Use it to produce test documents that feed TASKS and implementation work.

How this skill works

The skill guides authors through a validated TSPEC authoring workflow: verify upstream artifacts, pick a TSPEC type (UTEST/ITEST/STEST/FTEST), reserve an ID, and populate mandatory sections like Document Control, Test Scope, Test Case Index, Test Case Details, Coverage Matrix, and Traceability. It enforces naming and element ID patterns (TSPEC.NN.TT.SS), mandates cumulative upstream tags, and provides type-specific validation scripts and quality checks.

When to use it

You have completed BRD through SPEC (Layers 1–9) and need to define tests before coding
You follow a Test-Driven Development workflow and want TASKS-ready test specs
You must produce unit, integration, smoke, or functional test artifacts with traceability
You need to enforce coverage targets and document error cases and pseudocode
You want standardized TSPEC files that feed downstream TASKS and code work

Best practices

Always verify and reference only existing upstream artifacts; do not invent or placeholder missing docs
Complete the Document Control section first, including SPEC reference and TASKS-Ready Score
Assign Element IDs using the TSPEC.NN.TT.SS pattern and ensure element type code matches document folder
Include I/O tables, pseudocode, and explicit error cases for each test case; add sequence diagrams for complex integrations
Keep cumulative traceability tags from Layers 1–9 and update the TSPEC traceability matrix file

Example use cases

Write UTEST files to specify unit tests for a new authentication module with function and branch coverage targets
Create ITEST documents describing API contract validation and mock strategies between services
Author STEST smoke checks for post-deployment health with <5 minute execution and rollback steps
Produce FTEST files mapping system-level scenarios to SYS requirements and performance thresholds
Generate a TSPEC-00 index or traceability-template exempt from validation for project scaffolding

FAQ

What ID format must each test case use?

Use TSPEC.NN.TT.SS where TT is 40/41/42/43 for UTEST/ITEST/STEST/FTEST respectively.

What traceability tags are mandatory?

Include cumulative tags from Layers 1–9: @brd, @prd, @ears, @bdd, @adr, @sys, @req, @spec (add @ctr if CTR exists).

Can I use placeholders for missing upstream docs?

No. Reference only existing documents; use null only if the artifact genuinely does not exist and skip related tests if necessary.

Are there automated checks?

Yes. Use the provided type-specific validation scripts and the combined quality score scripts to run Tier 1 errors, warnings, and info checks.