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)

• Select report with latest timestamp/version.

• 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

Test Case Matrix

Environment Matrix

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 @req: 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:

• Parse new/modified specifications from SPEC

• Generate new test case stubs with auto-generated IDs

• Insert test cases in appropriate section

• Increment patch version (1.0.0 -> 1.0.1)

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

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:

• Perform all Tier 1 actions

• Generate detailed changelog section

• Mark affected existing tests for review

• Increment minor version (1.0.0 -> 1.1.0)

• 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

Existing Tests Marked for Review

Tests Deprecated (Not Deleted)

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

Trigger: Major SPEC overhaul requiring significant test restructuring.

Actions:

• Create archive manifest

• Archive current TSPEC version

• Generate regeneration request for doc-tspec-autopilot

• Increment major version (1.0.0 -> 2.0.0)

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

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

Preconditions

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

Test Steps

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

Files Created

Test Case Structure Repairs

Fixes Applied

Issues Requiring Manual Review

Upstream Drift Summary

Validation After Fix

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:

• Create backup in tmp/backup/TSPEC-NN_YYYYMMDD_HHMMSS/

• Copy all TSPEC files to backup location

• Apply fixes to original files

• 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

Implementation Plan Consistency (IPLAN-004)

• Treat plan-derived outputs as valid source mode and verify intent preservation from implementation plan scope/objectives.

• Validate upstream autopilot precedence assumption: --iplan > --ref > --prompt .

• Flag objective/scope conflicts between plan context and artifact output as blocking issues requiring clarification.

• Do not introduce legacy fallback paths such as docs-v2.0/00_REF .