doc-tspec-fixer

📁 vladm3105/aidoc-flow-framework 📅 8 days ago
9
总安装量
9
周安装量
#33101
全站排名
安装命令
npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-tspec-fixer

Agent 安装分布

codex 9
amp 8
github-copilot 8
kimi-cli 8
gemini-cli 8
cursor 8

Skill 文档

doc-tspec-fixer

Purpose

Automated fix skill that reads the latest review report and applies fixes to TSPEC (Test Specification) documents. This skill bridges the gap between doc-tspec-reviewer (which identifies issues) and the corrected TSPEC, enabling iterative improvement cycles.

Layer: 10 (TSPEC Quality Improvement)

Upstream: SPEC documents, TSPEC document, Review/Audit Report (TSPEC-NN.A_audit_report_vNNN.md preferred; TSPEC-NN.R_review_report_vNNN.md legacy-compatible)

Downstream: Fixed TSPEC, Fix Report (TSPEC-NN.F_fix_report_vNNN.md)


When to Use This Skill

Use doc-tspec-fixer when:

  • After Review: Run after doc-tspec-reviewer identifies issues
  • Iterative Improvement: Part of Review -> Fix -> Review cycle
  • Automated Pipeline: CI/CD integration for quality gates
  • Batch Fixes: Apply fixes to multiple TSPECs based on review reports
  • Test Case Structure Issues: Test cases have malformed structure

Do NOT use when:

  • No review report exists (run doc-tspec-reviewer first)
  • Creating new TSPEC (use doc-tspec or doc-tspec-autopilot)
  • Only need validation (use doc-tspec-validator)

Report Selection Precedence (Deterministic)

  1. Select report with latest timestamp/version.
  2. If timestamps/versions tie, prefer .A_audit_report_vNNN.md over .R_review_report_vNNN.md.

Skill Dependencies

Skill Purpose When Used
doc-tspec-audit Unified validator+reviewer wrapper Preferred upstream report source
doc-tspec-reviewer Source of issues to fix Input (reads review report)
doc-naming Element ID standards Fix element IDs
doc-tspec TSPEC creation rules Create missing sections
doc-spec SPEC traceability Validate upstream links

Workflow Overview

flowchart TD
  A[Input: TSPEC Path] --> B[Find Latest Audit/Review Report]
    B --> C{Review Found?}
    C -->|No| D[Run doc-tspec-reviewer First]
    C -->|Yes| E[Parse Review Report]

    E --> F[Categorize Issues]

    subgraph FixPhases["Fix Phases"]
        F --> F0[Phase 0: Fix Structure Violations]
        F0 --> G[Phase 1: Create Missing Files]
        G --> H[Phase 2: Fix Broken Links]
        H --> I[Phase 3: Fix Element IDs]
        I --> J[Phase 4: Fix Content Issues]
        J --> K[Phase 5: Update References]
        K --> K2[Phase 6: Handle Upstream Drift]
    end

    subgraph TestCaseFix["Test Case Structure Fixes"]
        K2 --> T1[Parse Test Cases]
        T1 --> T2{Structure Valid?}
        T2 -->|No| T3[Repair Test Case Structure]
        T2 -->|Yes| T4[Validate Test Coverage]
        T3 --> T4
    end

    T4 --> L[Write Fixed TSPEC]
    L --> M[Generate Fix Report]
    M --> N{Re-run Review?}
    N -->|Yes| O[Invoke doc-tspec-reviewer]
    O --> P{Score >= Threshold?}
    P -->|No, iterations < max| F
    P -->|Yes| Q[COMPLETE]
    N -->|No| Q

Fix Phases

Phase 0: Fix Structure Violations (CRITICAL)

Fixes TSPEC documents that are not in nested folders. This phase runs FIRST because all subsequent phases depend on correct folder structure.

Nested Folder Rule: ALL TSPEC documents MUST be in nested folders regardless of document size.

Required Structure:

TSPEC Type Required Location
UTEST docs/10_TSPEC/UTEST/UTEST-NN_{slug}/UTEST-NN_{slug}.md
ITEST docs/10_TSPEC/ITEST/ITEST-NN_{slug}/ITEST-NN_{slug}.md
STEST docs/10_TSPEC/STEST/STEST-NN_{slug}/STEST-NN_{slug}.md
FTEST docs/10_TSPEC/FTEST/FTEST-NN_{slug}/FTEST-NN_{slug}.md
PTEST docs/10_TSPEC/PTEST/PTEST-NN_{slug}/PTEST-NN_{slug}.md
SECTEST docs/10_TSPEC/SECTEST/SECTEST-NN_{slug}/SECTEST-NN_{slug}.md

Fix Actions:

Issue Code Issue Fix Action
REV-STR001 TSPEC not in nested folder Create folder, move file, update all links
REV-STR002 TSPEC folder name doesn’t match TSPEC ID Rename folder to match
REV-STR003 TSPEC >25KB should be sectioned Flag for manual review
REV-STR004 TSPEC not in correct subdirectory (UTEST/ITEST/STEST/FTEST) Move to correct subdirectory

Structure Fix Workflow:

def fix_tspec_structure(tspec_path: str) -> list[Fix]:
    """Fix TSPEC structure violations."""
    fixes = []

    filename = os.path.basename(tspec_path)
    parent_folder = os.path.dirname(tspec_path)

    # Extract TSPEC type, ID and slug from filename
    match = re.match(r'(UTEST|ITEST|STEST|FTEST)-(\d+)_([^/]+)\.md', filename)
    if not match:
        return []  # Cannot auto-fix invalid filename

    tspec_type = match.group(1)
    tspec_id = match.group(2)
    slug = match.group(3)
    expected_folder = f"{tspec_type}-{tspec_id}_{slug}"

    # Check if already in nested folder within correct subdirectory
    if os.path.basename(parent_folder) != expected_folder:
        # Create nested folder in correct subdirectory
        base_path = os.path.dirname(os.path.dirname(parent_folder))
        new_folder = os.path.join(base_path, tspec_type, expected_folder)
        os.makedirs(new_folder, exist_ok=True)

        # Move file
        new_path = os.path.join(new_folder, filename)
        shutil.move(tspec_path, new_path)
        fixes.append(f"Moved {tspec_path} to {new_path}")

        # Update upstream links in moved file
        content = Path(new_path).read_text()
        updated_content = content.replace('../09_SPEC/', '../../../09_SPEC/')
        updated_content = updated_content.replace('../../09_SPEC/', '../../../09_SPEC/')
        Path(new_path).write_text(updated_content)
        fixes.append(f"Updated relative links for nested folder structure")

    return fixes

Link Path Updates After Move:

Original Path Updated Path
../../09_SPEC/SPEC-01_slug/SPEC-01.yaml ../../../09_SPEC/SPEC-01_slug/SPEC-01.yaml

Phase 1: Create Missing Files

Creates files that are referenced but don’t exist.

Scope:

Missing File Action Template Used
TSPEC-NN_test_data.yaml Create test data file Test data template
TSPEC-NN_fixtures.yaml Create test fixtures file Fixtures template
TSPEC-NN_matrix.md Create test matrix Matrix template
Reference docs Create placeholder REF template

Test Data Template:

# TSPEC-NN: Test Data Definitions
# Auto-generated by doc-tspec-fixer - requires completion

test_data:
  version: "1.0.0"
  tspec_id: TSPEC-NN
  created: "YYYY-MM-DD"
  status: draft

datasets:
  # TODO: Add test datasets
  valid_inputs:
    - id: TD-001
      description: "Valid input data set 1"
      data:
        # Add data fields

  invalid_inputs:
    - id: TD-002
      description: "Invalid input data set 1"
      data:
        # Add data fields

  edge_cases:
    - id: TD-003
      description: "Edge case data set 1"
      data:
        # Add data fields

boundary_values:
  # TODO: Define boundary values for testing
  - field: example_field
    min: 0
    max: 100
    boundary_tests:
      - value: -1
        expected: error
      - value: 0
        expected: success
      - value: 100
        expected: success
      - value: 101
        expected: error

Test Fixtures Template:

# TSPEC-NN: Test Fixtures
# Auto-generated by doc-tspec-fixer - requires completion

fixtures:
  version: "1.0.0"
  tspec_id: TSPEC-NN
  created: "YYYY-MM-DD"

setup:
  # TODO: Define setup fixtures
  database:
    - name: test_db_setup
      description: "Initialize test database"
      actions:
        - action: create_schema
        - action: seed_data

  services:
    - name: mock_api_setup
      description: "Setup mock API endpoints"

teardown:
  # TODO: Define teardown fixtures
  database:
    - name: test_db_cleanup
      actions:
        - action: drop_schema

Test Matrix Template:

---
title: "TSPEC-NN: Test Matrix"
tags:
  - tspec
  - test-matrix
  - layer-10
custom_fields:
  document_type: test-matrix
  artifact_type: TSPEC-MATRIX
  layer: 10
  parent_tspec: TSPEC-NN
---

# TSPEC-NN Test Matrix

## Coverage Summary

| Requirement | Test Cases | Pass | Fail | Skip | Coverage |
|-------------|------------|------|------|------|----------|
| REQ-XX.YY.ZZ | TC-001, TC-002 | - | - | - | - |

## Test Case Matrix

| Test ID | Requirement | Priority | Type | Status |
|---------|-------------|----------|------|--------|
| TC-001 | REQ-XX.YY.ZZ | P1 | Unit | Pending |

## Environment Matrix

| Environment | OS | Browser/Runtime | Status |
|-------------|----|-----------------| -------|
| CI | Linux | Node 18 | Pending |

---

*Created by doc-tspec-fixer as placeholder. Complete this document.*

Phase 2: Fix Broken Links

Updates links to point to correct locations.

Fix Actions:

Issue Code Issue Fix Action
REV-L001 Broken internal link Update path or create target file
REV-L002 External link unreachable Add warning comment, keep link
REV-L003 Absolute path used Convert to relative path
REV-L008 Test data reference broken Update test data path
REV-L009 Fixture reference broken Update fixture path

Path Resolution Logic:

def fix_link_path(tspec_location: str, target_path: str) -> str:
    """Calculate correct relative path based on TSPEC location."""

    # TSPEC files: docs/10_TSPEC/TSPEC-01.md
    # Test data: docs/10_TSPEC/data/
    # Fixtures: docs/10_TSPEC/fixtures/

    if is_test_data_reference(target_path):
        return fix_test_data_ref(tspec_location, target_path)
    elif is_fixture_reference(target_path):
        return fix_fixture_ref(tspec_location, target_path)
    else:
        return calculate_relative_path(tspec_location, target_path)

Phase 3: Fix Element IDs

Converts invalid element IDs to correct format.

Conversion Rules:

Pattern Issue Conversion
TSPEC.NN.XX.SS Invalid type code Convert to valid TSPEC code
TC-XXX Legacy pattern TSPEC.NN.40.SS (Test Case)
TS-XXX Legacy pattern TSPEC.NN.41.SS (Test Suite)
TD-XXX Legacy pattern TSPEC.NN.42.SS (Test Data)
TF-XXX Legacy pattern TSPEC.NN.43.SS (Test Fixture)

Type Code Mapping (TSPEC-specific):

Invalid Code Valid Code Element Type
01-39 40 Test Case
N/A 41 Test Suite
N/A 42 Test Data
N/A 43 Test Fixture

Valid TSPEC Type Codes:

Code Element Type Description
40 UTEST Unit test case specification
41 ITEST Integration test case specification
42 STEST Smoke test case specification
43 FTEST Functional test case specification
44 PTEST Performance test case specification
45 SECTEST Security test case specification

Regex Patterns:

# Find element IDs with invalid type codes for TSPEC
invalid_tspec_type = r'TSPEC\.(\d{2})\.(?!40|41|42|43)(\d{2})\.(\d{2})'

# Find legacy patterns
legacy_tc = r'###\s+TC-(\d+):'
legacy_ts = r'###\s+TS-(\d+):'
legacy_td = r'###\s+TD-(\d+):'
legacy_tf = r'###\s+TF-(\d+):'

Phase 4: Fix Content Issues

Addresses placeholders and incomplete content.

Fix Actions:

Issue Code Issue Fix Action
REV-P001 [TODO] placeholder Flag for manual completion (cannot auto-fix)
REV-P002 [TBD] placeholder Flag for manual completion (cannot auto-fix)
REV-P003 Template date YYYY-MM-DD Replace with current date
REV-P004 Template name [Name] Replace with metadata author or flag
REV-P005 Empty section Add minimum template content
REV-T001 Missing test steps Add placeholder steps structure
REV-T002 Missing expected results Add placeholder expected results
REV-T003 Missing preconditions Add placeholder preconditions

Auto-Replacements:

replacements = {
    'YYYY-MM-DDTHH:MM:SS': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
    'YYYY-MM-DD': datetime.now().strftime('%Y-%m-%d'),
    'MM/DD/YYYY': datetime.now().strftime('%m/%d/%Y'),
    '[Current date]': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
}

Test Case Structure Repair:

Missing Element Added Template
Preconditions **Preconditions**: [TODO: Define preconditions]
Test Steps **Steps**:\n1. [TODO: Add step 1]\n2. [TODO: Add step 2]
Expected Results **Expected Results**: [TODO: Define expected outcome]
Priority **Priority**: P2 (default)
Test Type **Type**: Functional (default)

Phase 5: Update References

Ensures traceability and cross-references are correct.

Fix Actions:

Issue Fix Action
Missing @spec: reference Add SPEC traceability tag
Missing @req: reference Add REQ traceability tag (via SPEC)
Incorrect upstream path Update to correct relative path
Missing traceability entry Add to traceability matrix

SPEC Traceability Fix:

<!-- Before -->
## TC-001: User Authentication Test

<!-- After -->
## TC-001: User Authentication Test

@spec: [SPEC-01.auth.login](../09_SPEC/SPEC-01.md#auth-login)
@req: [REQ-01.28.01](../07_REQ/REQ-01.md#req-01-28-01)

Phase 6: Handle Upstream Drift (Auto-Merge)

Addresses issues where upstream SPEC documents have changed since TSPEC creation using a tiered auto-merge system.

6.0.1 Hash Validation Fixes

FIX-H001: Invalid Hash Placeholder

Trigger: Hash contains placeholder instead of SHA-256

Fix:

sha256sum <upstream_file_path> | cut -d' ' -f1

Update cache with: sha256:<64_hex_output>

FIX-H002: Missing Hash Prefix

Trigger: 64 hex chars but missing sha256: prefix

Fix: Prepend sha256: to value

FIX-H003: Upstream File Not Found

Trigger: Cannot compute hash (file missing)

Fix: Set drift_detected: true, add to manual review

Code Description Auto-Fix Severity
FIX-H001 Replace placeholder hash with actual SHA-256 Yes Error
FIX-H002 Add missing sha256: prefix Yes Warning
FIX-H003 Upstream file not found Partial Error

Upstream/Downstream Context:

  • Upstream: SPEC (Layer 9) – Test specifications derive from specifications
  • Downstream: TASKS (Layer 11) / Code – Tests inform implementation tasks

Drift Issue Codes (from doc-tspec-reviewer):

Code Severity Description Tier Mapping
REV-D001 Warning SPEC document modified after TSPEC Calculated per threshold
REV-D002 Warning Referenced specification content changed Calculated per threshold
REV-D003 Info SPEC document version incremented Tier 1
REV-D004 Info New specifications added to upstream Tier 1 or 2
REV-D005 Error Critical SPEC modification (>20% change) Tier 3

Tiered Auto-Merge Thresholds

Tier Change % Action Version Bump Requires Review
Tier 1 < 5% Auto-merge new test cases Patch (x.y.Z) No
Tier 2 5-15% Auto-merge with changelog Minor (x.Y.0) Summary only
Tier 3 > 15% Archive + regeneration trigger Major (X.0.0) Yes (mandatory)

Change Percentage Calculation

def calculate_change_percentage(spec_before: str, spec_after: str, tspec: str) -> float:
    """
    Calculate drift percentage based on:
    1. Specification section changes affecting test cases
    2. New requirements requiring new tests
    3. Modified requirements requiring test updates
    4. Removed requirements requiring test deprecation
    """
    spec_elements = extract_testable_elements(spec_before)
    spec_elements_new = extract_testable_elements(spec_after)
    tspec_coverage = extract_test_coverage(tspec)

    added = spec_elements_new - spec_elements
    removed = spec_elements - spec_elements_new
    modified = detect_modifications(spec_before, spec_after)

    total_elements = len(spec_elements_new)
    changed_elements = len(added) + len(removed) + len(modified)

    return (changed_elements / total_elements) * 100 if total_elements > 0 else 0

Test ID Patterns for TSPEC

Format: {TYPE}-NN-TC-SS

Type Description Example
UTEST Unit Test UTEST-01-TC-01
ITEST Integration Test ITEST-01-TC-01
STEST System Test STEST-01-TC-01
FTEST Functional Test FTEST-01-TC-01
PTEST Performance Test PTEST-01-TC-01
SECTEST Security Test SECTEST-01-TC-01

Where:

  • NN = TSPEC document number (01-99)
  • TC = Test Case identifier
  • SS = Sequence number within type (01-99)

Auto-Generated ID Example:

def generate_test_id(tspec_num: int, test_type: str, existing_ids: list) -> str:
    """Generate next available test ID."""
    type_prefix = test_type.upper()  # UTEST, ITEST, etc.
    existing_for_type = [id for id in existing_ids if id.startswith(f"{type_prefix}-{tspec_num:02d}-TC-")]

    if existing_for_type:
        max_seq = max(int(id.split("-")[-1]) for id in existing_for_type)
        next_seq = max_seq + 1
    else:
        next_seq = 1

    return f"{type_prefix}-{tspec_num:02d}-TC-{next_seq:02d}"

# Example: UTEST-01-TC-13 (13th unit test in TSPEC-01)

Tier 1: Auto-Merge (< 5% Change)

Trigger: Minor SPEC updates that require additional test coverage.

Actions:

  1. Parse new/modified specifications from SPEC
  2. Generate new test case stubs with auto-generated IDs
  3. Insert test cases in appropriate section
  4. Increment patch version (1.0.0 -> 1.0.1)
  5. Update drift cache with merge record

Example Auto-Generated Test Case:

## UTEST-01-TC-13: [Auto-Generated] Validate new_field parameter

@spec: [SPEC-01.api.new_field](../09_SPEC/SPEC-01.md#api-new-field)
@drift-merge: Tier-1 auto-merge on 2026-02-10
@status: PENDING_REVIEW

**Priority**: P2
**Type**: Unit

### Preconditions

[TODO: Define preconditions based on SPEC-01.api.new_field]

### Test Steps

| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | [TODO: Derived from SPEC-01.api.new_field] | [TODO] |

### Expected Results

[TODO: Define expected outcome based on SPEC-01.api.new_field]

Tier 2: Auto-Merge with Changelog (5-15% Change)

Trigger: Moderate SPEC updates affecting multiple test cases.

Actions:

  1. Perform all Tier 1 actions
  2. Generate detailed changelog section
  3. Mark affected existing tests for review
  4. Increment minor version (1.0.0 -> 1.1.0)
  5. Create drift summary in fix report

Changelog Section Format:

## Drift Changelog (Tier 2 Auto-Merge)

**Merge Date**: 2026-02-10T16:00:00
**SPEC Version**: SPEC-01 v2.3.0 -> v2.4.0
**Change Percentage**: 8.5%
**Version Bump**: 1.2.0 -> 1.3.0

### New Test Cases Added

| Test ID | Source Spec | Description |
|---------|-------------|-------------|
| ITEST-01-TC-08 | SPEC-01.api.batch_endpoint | Batch processing integration test |
| UTEST-01-TC-14 | SPEC-01.validation.new_rule | New validation rule unit test |

### Existing Tests Marked for Review

| Test ID | Reason | Action Required |
|---------|--------|-----------------|
| UTEST-01-TC-03 | Upstream spec modified | Review expected results |
| ITEST-01-TC-02 | API contract changed | Update test steps |

### Tests Deprecated (Not Deleted)

| Test ID | Reason | Status |
|---------|--------|--------|
| UTEST-01-TC-05 | Spec section removed | [DEPRECATED] |

Tier 3: Archive and Regeneration (> 15% Change)

Trigger: Major SPEC overhaul requiring significant test restructuring.

Actions:

  1. Create archive manifest
  2. Archive current TSPEC version
  3. Generate regeneration request for doc-tspec-autopilot
  4. Increment major version (1.0.0 -> 2.0.0)
  5. Flag for mandatory human review

Archive Manifest Format:

# TSPEC-01_archive_manifest.yaml
archive:
  tspec_id: TSPEC-01
  archived_version: "1.5.2"
  archive_date: "2026-02-10T16:00:00"
  archive_reason: "Tier 3 drift - SPEC changes exceed 15%"
  change_percentage: 23.4

  upstream_trigger:
    document: SPEC-01.md
    previous_version: "2.3.0"
    current_version: "3.0.0"
    modification_date: "2026-02-10T14:00:00"

archived_tests:
  total_count: 25
  by_type:
    UTEST: 12
    ITEST: 8
    STEST: 3
    FTEST: 2

  deprecated_not_deleted:
    - id: UTEST-01-TC-05
      reason: "Spec section FR-001.3 removed"
      original_spec_ref: "SPEC-01.fr.001.3"
    - id: ITEST-01-TC-03
      reason: "Integration point deprecated"
      original_spec_ref: "SPEC-01.api.legacy"

regeneration:
  triggered: true
  target_skill: doc-tspec-autopilot
  new_version: "2.0.0"
  preserve_deprecated: true

archive_location: "docs/10_TSPEC/archive/TSPEC-01_v1.5.2/"

No-Deletion Policy

CRITICAL: Tests are NEVER deleted, only marked as deprecated.

Deprecation Format:

## [DEPRECATED] UTEST-01-TC-05: Validate legacy_field parameter

@status: DEPRECATED
@deprecated-date: 2026-02-10
@deprecated-reason: Upstream SPEC-01.fr.001.3 removed in v3.0.0
@original-spec: [SPEC-01.fr.001.3](../09_SPEC/SPEC-01.md#fr-001-3) (no longer exists)

> **DEPRECATION NOTICE**: This test case is deprecated and will not be executed.
> It is preserved for historical traceability and audit purposes.

**Priority**: P2
**Type**: Unit

[Original test content preserved below...]

Deprecation Rules:

Scenario Action Marker
SPEC section removed Mark deprecated [DEPRECATED]
SPEC requirement obsoleted Mark deprecated [DEPRECATED]
Test superseded by new test Mark deprecated with reference [DEPRECATED] See: NEW-TC-ID
Test temporarily disabled Mark skipped (not deprecated) [SKIP]

Enhanced Drift Cache

The drift cache tracks merge history for audit and rollback purposes.

Cache Location: .drift_cache.json (project root or docs folder)

Enhanced Structure:

{
  "version": "2.0",
  "last_updated": "2026-02-10T16:00:00",
  "documents": {
    "TSPEC-01": {
      "current_version": "1.3.0",
      "last_check": "2026-02-10T16:00:00",
      "upstream": {
        "SPEC-01": {
          "last_version": "2.4.0",
          "last_modified": "2026-02-10T14:00:00",
          "content_hash": "sha256:abc123..."
        }
      },
      "merge_history": [
        {
          "merge_date": "2026-02-10T16:00:00",
          "tier": 1,
          "change_percentage": 3.2,
          "version_before": "1.2.5",
          "version_after": "1.2.6",
          "tests_added": ["UTEST-01-TC-13"],
          "tests_modified": [],
          "tests_deprecated": [],
          "auto_merged": true
        },
        {
          "merge_date": "2026-02-08T10:00:00",
          "tier": 2,
          "change_percentage": 8.5,
          "version_before": "1.1.0",
          "version_after": "1.2.0",
          "tests_added": ["ITEST-01-TC-08", "UTEST-01-TC-14"],
          "tests_modified": ["UTEST-01-TC-03", "ITEST-01-TC-02"],
          "tests_deprecated": ["UTEST-01-TC-05"],
          "auto_merged": true,
          "changelog_ref": "TSPEC-01.md#drift-changelog-2026-02-08"
        }
      ],
      "deprecated_tests": [
        {
          "id": "UTEST-01-TC-05",
          "deprecated_date": "2026-02-08",
          "reason": "SPEC section FR-001.3 removed",
          "original_spec_ref": "SPEC-01.fr.001.3"
        }
      ]
    }
  }
}

Drift Fix Actions Summary

Tier Change % Auto-Fix Version Tests Added Tests Modified Tests Deprecated Archive
1 < 5% Yes Patch Auto-generate None None No
2 5-15% Yes Minor Auto-generate Flag for review Mark deprecated No
3 > 15% No Major Regenerate all N/A Preserve all Yes

Drift Marker Format (retained for backward compatibility):

<!-- DRIFT: SPEC-01.md modified 2026-02-08 (TSPEC created 2026-02-05) -->
<!-- DRIFT-TIER: 2 | CHANGE: 8.5% | AUTO-MERGED: 2026-02-10 -->
@spec: [SPEC-01.auth.login](../09_SPEC/SPEC-01.md#auth-login)

Test Case Structure Fixes

TSPEC documents contain structured test cases. This section details specific test case repair strategies.

Test Case Detection

def find_test_cases(content: str) -> list:
    """Find all test cases in TSPEC content."""
    # Match test case headers
    pattern = r'##\s+(TC-\d+|TSPEC\.\d{2}\.40\.\d{2}):\s+(.+)'
    return re.findall(pattern, content)

Required Test Case Elements

Element Required Default Value
ID Yes Generate from pattern
Title Yes “[TODO: Add title]”
Preconditions Yes “[TODO: Define preconditions]”
Steps Yes Numbered placeholder list
Expected Results Yes “[TODO: Define expected outcome]”
Priority No P2
Type No Functional
Status No Pending

Test Case Template

## TSPEC.NN.40.SS: [Test Case Title]

**Priority**: P1 | P2 | P3
**Type**: Unit | Integration | System | Performance
**Status**: Pending | In Progress | Pass | Fail | Skip

@spec: [SPEC-XX.section](../09_SPEC/SPEC-XX.md#section)

### Preconditions

1. [Precondition 1]
2. [Precondition 2]

### Test Steps

| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | [Action 1] | [Expected 1] |
| 2 | [Action 2] | [Expected 2] |

### Expected Results

[Overall expected outcome description]

### Test Data

- **Input**: [Input data reference]
- **Expected Output**: [Expected output reference]

Structure Repair Actions

Issue Repair Action
Missing preconditions section Add section with placeholder
Missing steps table Add table structure
Missing expected results Add section with placeholder
Malformed steps table Repair table structure
Missing SPEC reference Add @spec placeholder

Command Usage

Basic Usage

# Fix TSPEC based on latest review
/doc-tspec-fixer TSPEC-01

# Fix with explicit audit report (preferred)
/doc-tspec-fixer TSPEC-01 --review-report TSPEC-01.A_audit_report_v001.md

# Fix with explicit legacy review report (supported)
/doc-tspec-fixer TSPEC-01 --review-report TSPEC-01.R_review_report_v001.md

# Fix and re-run review
/doc-tspec-fixer TSPEC-01 --revalidate

# Fix with iteration limit
/doc-tspec-fixer TSPEC-01 --revalidate --max-iterations 3

# Fix test case structure only
/doc-tspec-fixer TSPEC-01 --fix-types test_cases

Options

Option Default Description
--review-report latest Specific review report to use
--revalidate false Run reviewer after fixes
--max-iterations 3 Max fix-review cycles
--fix-types all Specific fix types (comma-separated)
--create-missing true Create missing reference files
--backup true Backup TSPEC before fixing
--dry-run false Preview fixes without applying
--validate-structure true Validate test case structure after fixes
--acknowledge-drift false Interactive drift acknowledgment mode
--update-drift-cache true Update .drift_cache.json after fixes

Fix Types

Type Description
missing_files Create missing test data, fixture, matrix docs
broken_links Fix link paths
element_ids Convert invalid/legacy element IDs (40-43)
content Fix placeholders, dates, names
references Update SPEC traceability and cross-references
drift Handle upstream drift detection issues
test_cases Fix test case structure issues
all All fix types (default)

Output Artifacts

Fix Report

Nested Folder Rule: ALL TSPEC use nested folders (TSPEC-NN_{slug}/) regardless of size. Fix reports are stored alongside the TSPEC document in the nested folder.

File Naming: TSPEC-NN.F_fix_report_vNNN.md

Location: Inside the TSPEC nested folder: docs/10_TSPEC/TSPEC-NN_{slug}/

Structure:

---
title: "TSPEC-NN.F: Fix Report v001"
tags:
  - tspec
  - fix-report
  - quality-assurance
custom_fields:
  document_type: fix-report
  artifact_type: TSPEC-FIX
  layer: 10
  parent_doc: TSPEC-NN
  source_review: TSPEC-NN.A_audit_report_v001.md
  fix_date: "YYYY-MM-DDTHH:MM:SS"
  fix_tool: doc-tspec-fixer
  fix_version: "1.0"
---

# TSPEC-NN Fix Report v001

## Summary

| Metric | Value |
|--------|-------|
| Source Review | TSPEC-NN.A_audit_report_v001.md |
| Issues in Review | 20 |
| Issues Fixed | 17 |
| Issues Remaining | 3 (manual review required) |
| Files Created | 2 |
| Files Modified | 1 |
| Test Cases Repaired | 5 |

## Files Created

| File | Type | Location |
|------|------|----------|
| TSPEC-01_test_data.yaml | Test Data | docs/10_TSPEC/data/ |
| TSPEC-01_fixtures.yaml | Test Fixtures | docs/10_TSPEC/fixtures/ |

## Test Case Structure Repairs

| Test Case | Issue | Repair Applied |
|-----------|-------|----------------|
| TC-001 | Missing preconditions | Added placeholder section |
| TC-003 | Missing steps table | Added table structure |
| TC-005 | Malformed expected results | Repaired section format |
| TC-007 | Missing SPEC reference | Added @spec placeholder |
| TC-009 | Invalid element ID | Converted to TSPEC.01.40.09 |

## Fixes Applied

| # | Issue Code | Issue | Fix Applied | File |
|---|------------|-------|-------------|------|
| 1 | REV-N004 | Invalid element type | Converted to type 40 | TSPEC-01.md |
| 2 | REV-T001 | Missing test steps | Added table structure | TSPEC-01.md |
| 3 | REV-L003 | Absolute path used | Converted to relative | TSPEC-01.md |

## Issues Requiring Manual Review

| # | Issue Code | Issue | Location | Reason |
|---|------------|-------|----------|--------|
| 1 | REV-P001 | [TODO] placeholder | TSPEC-01.md:L78 | Test content needed |
| 2 | REV-D002 | SPEC content changed | SPEC-01.auth | Review specification update |

## Upstream Drift Summary

| Upstream Document | Reference | Modified | TSPEC Updated | Days Stale | Action Required |
|-------------------|-----------|----------|---------------|------------|-----------------|
| SPEC-01.md | TSPEC-01:L57 | 2026-02-08 | 2026-02-05 | 3 | Review for changes |

## Validation After Fix

| Metric | Before | After | Delta |
|--------|--------|-------|-------|
| Review Score | 82 | 94 | +12 |
| Errors | 6 | 0 | -6 |
| Warnings | 8 | 3 | -5 |
| Valid Test Cases | 12/17 | 17/17 | +5 |

## Next Steps

1. Complete [TODO] placeholders in test case steps
2. Review upstream SPEC drift
3. Populate test data in TSPEC-01_test_data.yaml
4. Run `/doc-tspec-reviewer TSPEC-01` to verify fixes

Integration with Autopilot

This skill is invoked by doc-tspec-autopilot in the Review -> Fix cycle:

flowchart LR
    subgraph Phase5["Phase 5: Review & Fix Cycle"]
        A[doc-tspec-reviewer] --> B{Score >= 90?}
        B -->|No| C[doc-tspec-fixer]
        C --> D{Iteration < Max?}
        D -->|Yes| A
        D -->|No| E[Flag for Manual Review]
        B -->|Yes| F[PASS]
    end

Autopilot Integration Points:

Phase Action Skill
Phase 5a Run initial review doc-tspec-reviewer
Phase 5b Apply fixes if issues found doc-tspec-fixer
Phase 5c Re-run review doc-tspec-reviewer
Phase 5d Repeat until pass or max iterations Loop

Error Handling

Recovery Actions

Error Action
Review report not found Prompt to run doc-tspec-reviewer first
Cannot create file (permissions) Log error, continue with other fixes
Cannot parse review report Abort with clear error message
Test case parse error Attempt repair, flag if unrecoverable
Max iterations exceeded Generate report, flag for manual review

Backup Strategy

Before applying any fixes:

  1. Create backup in tmp/backup/TSPEC-NN_YYYYMMDD_HHMMSS/
  2. Copy all TSPEC files to backup location
  3. Apply fixes to original files
  4. If error during fix, restore from backup

Related Skills

Skill Relationship
doc-tspec-reviewer Provides review report (input)
doc-tspec-autopilot Orchestrates Review -> Fix cycle
doc-tspec-validator Structural validation
doc-naming Element ID standards
doc-tspec TSPEC creation rules
doc-spec SPEC upstream traceability

Version History

Version Date Changes
2.3 2026-02-27 Normalized frontmatter to metadata schema with versioning_policy; updated upstream contract to audit-first (.A_ preferred) with .R_ compatibility; added deterministic report precedence rule; updated fixer command and report examples for audit-wrapper flow
2.2 2026-02-26 Added PTEST (code 44) and SECTEST (code 45) support; Updated type codes table to use correct test type names; Added PTEST/SECTEST to nested folder table
2.1 2026-02-11 Structure Compliance: Added Phase 0 for nested folder rule enforcement (REV-STR001-STR004); Runs FIRST before other fix phases
2.0 2026-02-10 Enhanced Phase 6 with tiered auto-merge system (Tier 1: <5% auto-merge patch, Tier 2: 5-15% auto-merge minor with changelog, Tier 3: >15% archive and regenerate major); Added test ID patterns for TSPEC (UTEST/ITEST/STEST/FTEST/PTEST/SECTEST-NN-TC-SS format); Implemented no-deletion policy with [DEPRECATED] markers; Enhanced drift cache with merge history tracking; Added archive manifest creation for Tier 3; Auto-generated test ID support
1.0 2026-02-10 Initial skill creation; 6-phase fix workflow; Test case structure repair; Test data and fixture file generation; Element ID conversion (types 40-43); SPEC drift handling; Integration with autopilot Review->Fix cycle