doc-tspec-fixer
npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-tspec-fixer
Agent 安装分布
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-revieweridentifies 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-reviewerfirst) - Creating new TSPEC (use
doc-tspecordoc-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.mdover.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 identifierSS= 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](../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:
- 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
| 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:
- 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](../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:
- 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 |