doc-tspec-fixer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

TSPEC-NN.R_review_report_vNNN.md

)

Downstream: Fixed TSPEC, Fix Report (

TSPEC-NN.F_fix_report_vNNN.md

)

一款自动化修复工具，可读取最新评审报告并对TSPEC（测试规范）文档进行修复。该工具填补了

doc-tspec-reviewer

（用于识别问题）与修正后TSPEC文档之间的空白，支持迭代优化循环。

层级：10（TSPEC质量优化）

上游依赖：SPEC文档、TSPEC文档、评审报告（

TSPEC-NN.R_review_report_vNNN.md

）

下游产出：修复后的TSPEC文档、修复报告（

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

在以下场景使用

doc-tspec-fixer

：

评审完成后：在
```
doc-tspec-reviewer
```
识别出问题后运行
迭代优化：作为「评审→修复→评审」循环的一部分
自动化流水线：集成到CI/CD流程中作为质量门控
批量修复：基于评审报告对多个TSPEC文档执行修复
测试用例结构问题：测试用例存在格式错误

请勿在以下场景使用：

无评审报告时（请先运行
```
doc-tspec-reviewer
```
）
创建新TSPEC文档时（使用
```
doc-tspec
```
或
```
doc-tspec-autopilot
```
）
仅需验证时（使用
```
doc-tspec-validator
```
）

Skill Dependencies

工具依赖

Skill	Purpose	When Used
`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

工具	用途	使用时机
`doc-tspec-reviewer`	提供待修复的问题列表	输入（读取评审报告）
`doc-naming`	元素ID标准	修复元素ID
`doc-tspec`	TSPEC文档创建规则	创建缺失章节
`doc-spec`	SPEC可追溯性	验证上游链接

Workflow Overview

工作流程概览

mermaid

flowchart TD
    A[Input: TSPEC Path] --> B[Find Latest 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

mermaid

flowchart TD
    A[输入: TSPEC路径] --> B[查找最新评审报告]
    B --> C{找到评审报告?}
    C -->|否| D[先运行doc-tspec-reviewer]
    C -->|是| E[解析评审报告]

    E --> F[分类问题]

    subgraph FixPhases["修复阶段"]
        F --> F0[阶段0: 修复结构违规]
        F0 --> G[阶段1: 创建缺失文件]
        G --> H[阶段2: 修复断链]
        H --> I[阶段3: 修复元素ID]
        I --> J[阶段4: 修复内容问题]
        J --> K[阶段5: 更新引用]
        K --> K2[阶段6: 处理上游漂移]
    end

    subgraph TestCaseFix["测试用例结构修复"]
        K2 --> T1[解析测试用例]
        T1 --> T2{结构是否有效?}
        T2 -->|否| T3[修复测试用例结构]
        T2 -->|是| T4[验证测试覆盖率]
        T3 --> T4
    end

    T4 --> L[写入修复后的TSPEC文档]
    L --> M[生成修复报告]
    M --> N{重新运行评审?}
    N -->|是| O[调用doc-tspec-reviewer]
    O --> P[分数≥阈值?]
    P -->|否, 迭代次数<最大值| F
    P -->|是| Q[完成]
    N -->|否| Q

Fix Phases

修复阶段

Phase 0: Fix Structure Violations (CRITICAL)

阶段0：修复结构违规（关键）

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`

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:

python

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`

修复未存放在嵌套文件夹中的TSPEC文档。该阶段优先运行，因为后续所有阶段都依赖正确的文件夹结构。

嵌套文件夹规则：所有TSPEC文档无论大小，都必须存放在嵌套文件夹中。

要求结构:

TSPEC类型	要求存放位置
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`

修复操作:

问题代码	问题描述	修复动作
REV-STR001	TSPEC未在嵌套文件夹中	创建文件夹、移动文件、更新所有链接
REV-STR002	TSPEC文件夹名称与TSPEC ID不匹配	重命名文件夹以匹配ID
REV-STR003	TSPEC文件大于25KB需拆分章节	标记为需人工评审
REV-STR004	TSPEC未在正确子目录（UTEST/ITEST/STEST/FTEST）	移动到正确子目录

结构修复工作流:

python

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

移动后的链接路径更新:

原路径	更新后路径
`../../09_SPEC/SPEC-01_slug/SPEC-01.yaml`	`../../../09_SPEC/SPEC-01_slug/SPEC-01.yaml`

Phase 1: Create Missing Files

阶段1：创建缺失文件

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:

yaml

undefined

创建被引用但不存在的文件。

范围:

缺失文件	动作	使用模板
`TSPEC-NN_test_data.yaml`	创建测试数据文件	测试数据模板
`TSPEC-NN_fixtures.yaml`	创建测试夹具文件	夹具模板
`TSPEC-NN_matrix.md`	创建测试矩阵	矩阵模板
参考文档	创建占位符	REF模板

测试数据模板:

yaml

undefined

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

```yaml

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


**测试夹具模板**:

```yaml

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

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

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


**测试矩阵模板**:

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

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

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.

---

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

阶段2：修复断链

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:

python

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)

更新链接指向正确位置。

修复操作:

问题代码	问题描述	修复动作
REV-L001	内部链接断裂	更新路径或创建目标文件
REV-L002	外部链接不可访问	添加警告注释，保留链接
REV-L003	使用绝对路径	转换为相对路径
REV-L008	测试数据引用断裂	更新测试数据路径
REV-L009	夹具引用断裂	更新夹具路径

路径解析逻辑:

python

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

阶段3：修复元素ID

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	Test Case	Individual test case specification
41	Test Suite	Collection of related test cases
42	Test Data	Test data definition
43	Test Fixture	Test fixture/setup definition

Regex Patterns:

python

undefined

将无效的元素ID转换为正确格式。

转换规则:

模式	问题	转换方式
`TSPEC.NN.XX.SS`	无效类型代码	转换为有效的TSPEC代码
`TC-XXX`	旧版模式	`TSPEC.NN.40.SS` （测试用例）
`TS-XXX`	旧版模式	`TSPEC.NN.41.SS` （测试套件）
`TD-XXX`	旧版模式	`TSPEC.NN.42.SS` （测试数据）
`TF-XXX`	旧版模式	`TSPEC.NN.43.SS` （测试夹具）

TSPEC专属类型代码映射:

无效代码	有效代码	元素类型
01-39	40	测试用例
N/A	41	测试套件
N/A	42	测试数据
N/A	43	测试夹具

有效TSPEC类型代码:

代码	元素类型	描述
40	测试用例	单个测试用例规范
41	测试套件	相关测试用例的集合
42	测试数据	测试数据定义
43	测试夹具	测试夹具/初始化定义

正则表达式:

python

undefined

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

---

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

阶段4：修复内容问题

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:

python

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)

处理占位符和不完整内容。

修复操作:

问题代码	问题描述	修复动作
REV-P001	`[TODO]` 占位符	标记为需人工补充（无法自动修复）
REV-P002	`[TBD]` 占位符	标记为需人工补充（无法自动修复）
REV-P003	模板日期 `YYYY-MM-DD`	替换为当前日期
REV-P004	模板名称 `[Name]`	替换为元数据作者或标记为需补充
REV-P005	空章节	添加最小模板内容
REV-T001	缺失测试步骤	添加占位符步骤结构
REV-T002	缺失预期结果	添加占位符预期结果
REV-T003	缺失前置条件	添加占位符前置条件

自动替换规则:

python

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'),
}

测试用例结构修复:

缺失元素	添加的模板内容
前置条件	`前置条件: [TODO: 定义前置条件]`
测试步骤	`步骤:\n1. [TODO: 添加步骤1]\n2. [TODO: 添加步骤2]`
预期结果	`预期结果: [TODO: 定义预期结果]`
优先级	`优先级: P2` （默认值）
测试类型	`类型: 功能测试` （默认值）

Phase 5: Update References

阶段5：更新引用

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:

markdown

<!-- Before -->

确保可追溯性和交叉引用正确。

修复操作:

问题	修复动作
缺失 `@spec:` 引用	添加SPEC可追溯性标签
缺失 `@req:` 引用	通过SPEC添加REQ可追溯性标签
上游路径错误	更新为正确的相对路径
缺失可追溯性条目	添加到可追溯性矩阵

SPEC可追溯性修复示例:

markdown

<!-- 修复前 -->

TC-001: User Authentication Test

TC-001: 用户认证测试

TC-001: User Authentication Test

TC-001: 用户认证测试

@spec: SPEC-01.auth.login @req: REQ-01.28.01

---

@spec: SPEC-01.auth.login @req: REQ-01.28.01

---

Phase 6: Handle Upstream Drift (Auto-Merge)

阶段6：处理上游漂移（自动合并）

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

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

使用分层自动合并系统处理TSPEC创建后上游SPEC文档发生变更的问题。

上下游上下文:

上游: SPEC（层级9）- 测试规范源自需求规范
下游: TASKS（层级11）/代码 - 测试指导实现任务

漂移问题代码（来自

doc-tspec-reviewer

）:

代码	严重程度	描述	层级映射
REV-D001	警告	SPEC文档在TSPEC创建后被修改	根据阈值计算
REV-D002	警告	引用的规范内容已变更	根据阈值计算
REV-D003	信息	SPEC文档版本已升级	层级1
REV-D004	信息	上游添加了新规范	层级1或2
REV-D005	错误	SPEC关键修改（变更>20%）	层级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)

层级	变更百分比	动作	版本升级	是否需要评审
层级1	< 5%	自动合并新测试用例	补丁版本（x.y.Z）	否
层级2	5-15%	自动合并并生成变更日志	小版本（x.Y.0）	仅需摘要评审
层级3	> 15%	归档并触发重新生成	大版本（X.0.0）	是（强制）

Change Percentage Calculation

变更百分比计算

python

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

python

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

TSPEC测试ID格式

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:

python

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}"

格式:

{TYPE}-NN-TC-SS

类型	描述	示例
UTEST	单元测试	UTEST-01-TC-01
ITEST	集成测试	ITEST-01-TC-01
STEST	系统测试	STEST-01-TC-01
FTEST	功能测试	FTEST-01-TC-01
PTEST	性能测试	PTEST-01-TC-01
SECTEST	安全测试	SECTEST-01-TC-01

其中:

```
NN
```
= TSPEC文档编号（01-99）
```
TC
```
= 测试用例标识符
```
SS
```
= 同类型内的序号（01-99）

自动生成ID示例:

python

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)

示例: UTEST-01-TC-13（TSPEC-01中的第13个单元测试）

undefined

undefined

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

层级1：自动合并（变更<5%）

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:

markdown

undefined

触发条件: 微小的SPEC更新，需要补充测试覆盖率。

动作:

解析SPEC中的新增/修改规范
使用自动生成的ID生成新测试用例 stub
将测试用例插入到对应章节
升级补丁版本（1.0.0 -> 1.0.1）
在漂移缓存中记录合并记录

自动生成测试用例示例:

markdown

undefined

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

UTEST-01-TC-13: [自动生成] 验证new_field参数

@spec: SPEC-01.api.new_field @drift-merge: Tier-1 auto-merge on 2026-02-10 @status: PENDING_REVIEW

Priority: P2 Type: Unit

@spec: SPEC-01.api.new_field @drift-merge: 层级1自动合并于2026-02-10 @status: 待评审

优先级: P2 类型: 单元测试

Preconditions

前置条件

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

[TODO: 根据SPEC-01.api.new_field定义前置条件]

Test Steps

测试步骤

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

步骤	动作	预期结果
1	[TODO: 源自SPEC-01.api.new_field]	[TODO]

Expected Results

预期结果

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

undefined

[TODO: 根据SPEC-01.api.new_field定义预期结果]

undefined

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

层级2：自动合并并生成变更日志（变更5-15%）

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:

markdown

undefined

触发条件: 中等程度的SPEC更新，影响多个测试用例。

动作:

执行所有层级1的动作
生成详细的变更日志章节
标记受影响的现有测试用例需评审
升级小版本（1.0.0 -> 1.1.0）
在修复报告中生成漂移摘要

变更日志章节格式:

markdown

undefined

Drift Changelog (Tier 2 Auto-Merge)

漂移变更日志（层级2自动合并）

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

合并日期: 2026-02-10T16:00:00 SPEC版本: SPEC-01 v2.3.0 -> v2.4.0 变更百分比: 8.5% 版本升级: 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

测试ID	来源SPEC	描述
ITEST-01-TC-08	SPEC-01.api.batch_endpoint	批处理集成测试
UTEST-01-TC-14	SPEC-01.validation.new_rule	新验证规则单元测试

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

测试ID	原因	需执行动作
UTEST-01-TC-03	上游规范已修改	评审预期结果
ITEST-01-TC-02	API契约已变更	更新测试步骤

Tests Deprecated (Not Deleted)

已弃用测试用例（未删除）

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

undefined

测试ID	原因	状态
UTEST-01-TC-05	规范章节已移除	[已弃用]

undefined

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

层级3：归档并重新生成（变更>15%）

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:

yaml

undefined

触发条件: SPEC重大改版，需要大幅重构测试。

动作:

创建归档清单
归档当前TSPEC版本
触发
```
doc-tspec-autopilot
```
重新生成请求
升级大版本（1.0.0 -> 2.0.0）
标记为需强制人工评审

归档清单格式:

yaml

undefined

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/"

undefined

archive: tspec_id: TSPEC-01 archived_version: "1.5.2" archive_date: "2026-02-10T16:00:00" archive_reason: "层级3漂移 - SPEC变更超过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

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/"

undefined

No-Deletion Policy

不删除政策

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

Deprecation Format:

markdown

undefined

关键规则: 测试用例绝不删除，仅标记为已弃用。

弃用格式:

markdown

undefined

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

[已弃用] UTEST-01-TC-05: 验证legacy_field参数

@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]` |

@status: 已弃用 @deprecated-date: 2026-02-10 @deprecated-reason: 上游SPEC-01.fr.001.3在v3.0.0中已移除 @original-spec: SPEC-01.fr.001.3（已不存在）

弃用通知: 该测试用例已弃用，将不再执行。保留该用例是为了历史可追溯性和审计目的。

优先级: P2 类型: 单元测试

[以下保留原始测试内容...]


**弃用规则**:

| 场景 | 动作 | 标记 |
|----------|--------|--------|
| SPEC章节已移除 | 标记为已弃用 | `[已弃用]` |
| SPEC需求已过时 | 标记为已弃用 | `[已弃用]` |
| 测试用例被新用例替代 | 标记为已弃用并引用新用例 | `[已弃用] 参考: 新测试ID` |
| 测试用例临时禁用 | 标记为跳过（非弃用） | `[跳过]` |

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:

json

{
  "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_cache.json

（项目根目录或docs文件夹）

增强结构:

json

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

markdown

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

层级	变更百分比	自动修复	版本升级	新增测试用例	修改测试用例	弃用测试用例	归档
1	< 5%	是	补丁版本	自动生成	无	无	否
2	5-15%	是	小版本	自动生成	标记需评审	标记为已弃用	否
3	> 15%	否	大版本	重新生成所有	N/A	保留所有	是

漂移标记格式（兼容旧版本）:

markdown

<!-- 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.

TSPEC文档包含结构化测试用例。本节详细说明具体的测试用例修复策略。

Test Case Detection

测试用例检测

python

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)

python

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

元素	是否必填	默认值
ID	是	根据格式生成
标题	是	"[TODO: 添加标题]"
前置条件	是	"[TODO: 定义前置条件]"
步骤	是	编号占位符列表
预期结果	是	"[TODO: 定义预期结果]"
优先级	否	P2
类型	否	功能测试
状态	否	待处理

Test Case Template

测试用例模板

markdown

undefined

markdown

undefined

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

TSPEC.NN.40.SS: [测试用例标题]

@spec: SPEC-XX.section

优先级: P1 | P2 | P3 类型: 单元测试 | 集成测试 | 系统测试 | 性能测试状态: 待处理 | 进行中 | 通过 | 失败 | 跳过

@spec: SPEC-XX.section

Preconditions

前置条件

[Precondition 1]
[Precondition 2]

[前置条件1]
[前置条件2]

Test Steps

测试步骤

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

步骤	动作	预期结果
1	[动作1]	[预期结果1]
2	[动作2]	[预期结果2]

Expected Results

预期结果

[Overall expected outcome description]

[整体预期结果描述]

Test Data

测试数据

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

undefined

输入: [输入数据引用]
预期输出: [预期输出引用]

undefined

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

问题	修复动作
缺失前置条件章节	添加带占位符的章节
缺失步骤表格	添加表格结构
缺失预期结果	添加带占位符的章节
步骤表格格式错误	修复表格结构
缺失SPEC引用	添加@spec占位符

Command Usage

命令用法

Basic Usage

基础用法

bash

undefined

bash

undefined

Fix TSPEC based on latest review

根据最新评审报告修复TSPEC

/doc-tspec-fixer TSPEC-01

Fix with explicit review report

使用指定评审报告修复

/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

undefined

/doc-tspec-fixer TSPEC-01 --fix-types test_cases

undefined

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

选项	默认值	描述
`--review-report`	最新	使用的指定评审报告
`--revalidate`	false	修复后运行评审工具
`--max-iterations`	3	最大修复-评审循环次数
`--fix-types`	all	指定修复类型（逗号分隔）
`--create-missing`	true	创建缺失的引用文件
`--backup`	true	修复前备份TSPEC
`--dry-run`	false	预览修复内容但不实际应用
`--validate-structure`	true	修复后验证测试用例结构
`--acknowledge-drift`	false	交互式漂移确认模式
`--update-drift-cache`	true	修复后更新.drift_cache.json

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)

类型	描述
`missing_files`	创建缺失的测试数据、夹具、矩阵文档
`broken_links`	修复链接路径
`element_ids`	转换无效/旧版元素ID（40-43类型）
`content`	修复占位符、日期、名称
`references`	更新SPEC可追溯性和交叉引用
`drift`	处理上游漂移检测问题
`test_cases`	修复测试用例结构问题
`all`	所有修复类型（默认）

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:

markdown

---
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.R_review_report_v001.md
  fix_date: "YYYY-MM-DDTHH:MM:SS"
  fix_tool: doc-tspec-fixer
  fix_version: "1.0"
---

嵌套文件夹规则: 所有TSPEC使用嵌套文件夹（

TSPEC-NN_{slug}/

），无论大小。修复报告与TSPEC文档一起存储在嵌套文件夹中。

文件命名:

TSPEC-NN.F_fix_report_vNNN.md

存储位置: TSPEC嵌套文件夹内:

docs/10_TSPEC/TSPEC-NN_{slug}/

结构:

markdown

---
title: "TSPEC-NN.F: 修复报告 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.R_review_report_v001.md
  fix_date: "YYYY-MM-DDTHH:MM:SS"
  fix_tool: doc-tspec-fixer
  fix_version: "1.0"
---

TSPEC-NN Fix Report v001

TSPEC-NN 修复报告 v001

Summary

摘要

Metric	Value
Source Review	TSPEC-NN.R_review_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

指标	数值
来源评审报告	TSPEC-NN.R_review_report_v001.md
评审中发现的问题	20
已修复问题	17
剩余问题	3（需人工评审）
创建文件数	2
修改文件数	1
修复的测试用例数	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/

文件	类型	位置
TSPEC-01_test_data.yaml	测试数据	docs/10_TSPEC/data/
TSPEC-01_fixtures.yaml	测试夹具	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

测试用例	问题	应用的修复
TC-001	缺失前置条件	添加占位符章节
TC-003	缺失步骤表格	添加表格结构
TC-005	预期结果格式错误	修复章节格式
TC-007	缺失SPEC引用	添加@spec占位符
TC-009	无效元素ID	转换为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

#	问题代码	问题	应用的修复	文件
1	REV-N004	无效元素类型	转换为类型40	TSPEC-01.md
2	REV-T001	缺失测试步骤	添加表格结构	TSPEC-01.md
3	REV-L003	使用绝对路径	转换为相对路径	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

#	问题代码	问题	位置	原因
1	REV-P001	[TODO]占位符	TSPEC-01.md:L78	需要测试内容
2	REV-D002	SPEC内容已变更	SPEC-01.auth	需评审规范更新

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

上游文档	引用	修改日期	TSPEC更新日期	过期天数	需执行动作
SPEC-01.md	TSPEC-01:L57	2026-02-08	2026-02-05	3	评审变更内容

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

指标	修复前	修复后	变化量
评审分数	82	94	+12
错误数	6	0	-6
警告数	8	3	-5
有效测试用例数	12/17	17/17	+5

Next Steps

下一步动作

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

---

完成测试用例步骤中的[TODO]占位符
评审上游SPEC漂移
填充TSPEC-01_test_data.yaml中的测试数据
运行
```
/doc-tspec-reviewer TSPEC-01
```
验证修复结果

---

Integration with Autopilot

与Autopilot集成

This skill is invoked by

doc-tspec-autopilot

in the Review -> Fix cycle:

mermaid

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

该工具在「评审→修复」循环中被

doc-tspec-autopilot

调用:

mermaid

flowchart LR
    subgraph Phase5["阶段5: 评审&修复循环"]
        A[doc-tspec-reviewer] --> B{分数≥90?}
        B -->|否| C[doc-tspec-fixer]
        C --> D[迭代次数<最大值?]
        D -->|是| A
        D -->|否| E[标记为需人工评审]
        B -->|是| F[通过]
    end

Autopilot集成点:

阶段	动作	工具
阶段5a	运行初始评审	`doc-tspec-reviewer`
阶段5b	发现问题时应用修复	`doc-tspec-fixer`
阶段5c	重新运行评审	`doc-tspec-reviewer`
阶段5d	重复直到通过或达到最大迭代次数	循环

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

错误	动作
未找到评审报告	提示先运行 `doc-tspec-reviewer`
无法创建文件（权限问题）	记录错误，继续其他修复
无法解析评审报告	终止并显示清晰错误信息
测试用例解析错误	尝试修复，若无法恢复则标记
超过最大迭代次数	生成报告，标记为需人工评审

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

应用任何修复前:

在
```
tmp/backup/TSPEC-NN_YYYYMMDD_HHMMSS/
```
创建备份
将所有TSPEC文件复制到备份位置
对原始文件应用修复
若修复过程中出错，从备份恢复

Related Skills

Version History

版本历史

Version	Date	Changes
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

版本	日期	变更
2.1	2026-02-11	结构合规性: 添加阶段0用于强制嵌套文件夹规则（REV-STR001-STR004）；优先于其他阶段运行
2.0	2026-02-10	增强阶段6，添加分层自动合并系统（层级1: <5%自动合并补丁版本，层级2:5-15%自动合并小版本并生成变更日志，层级3:>15%归档并重新生成大版本）；添加TSPEC测试ID格式（UTEST/ITEST/STEST/FTEST/PTEST/SECTEST-NN-TC-SS）；实现不删除政策，添加[已弃用]标记；增强漂移缓存，跟踪合并历史；添加层级3归档清单；支持自动生成测试ID
1.0	2026-02-10	初始工具创建；6阶段修复工作流；测试用例结构修复；测试数据和夹具文件生成；元素ID转换（类型40-43）；SPEC漂移处理；与Autopilot的「评审→修复」循环集成

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

工具	关系
`doc-tspec-reviewer`	提供评审报告（输入）
`doc-tspec-autopilot`	编排「评审→修复」循环
`doc-tspec-validator`	结构验证
`doc-naming`	元素ID标准
`doc-tspec`	TSPEC文档创建规则
`doc-spec`	SPEC上游可追溯性