doc-tspec-autopilot（文档 tspec 自动驾驶仪）

doc-tspec-autopilot

Purpose

Automated Test Specifications (TSPEC) generation pipeline that processes SPEC documents to generate comprehensive test specifications for UTEST, ITEST, STEST, and FTEST with TASKS-Ready scoring.

Layer: 10

Upstream: SPEC (Layer 9)

Downstream: TASKS (Layer 11)

Input Contract (IPLAN-004 Standard)

• Supported modes:

- --ref <path> - --prompt "<text>" - --iplan <path|IPLAN-NNN>

• Precedence: --iplan > --ref > --prompt
• IPLAN resolution order:

1. Use explicit file path when it exists 2. Resolve work_plans/IPLAN-NNN*.md 3. Resolve governance/plans/IPLAN-NNN*.md 4. If multiple matches exist, fail with disambiguation request

• Merge conflict rule:

- Objective/scope conflicts between primary and supplemental sources are blocking and require user clarification.

Input Contract (IPLAN-004 Standard)

• Supported modes:

- --ref <path> - --prompt "<text>" - --iplan <path|IPLAN-NNN>

• Precedence: --iplan > --ref > --prompt
• IPLAN resolution order:

1. Use explicit file path when it exists 2. Resolve work_plans/IPLAN-NNN*.md 3. Resolve governance/plans/IPLAN-NNN*.md 4. If multiple matches exist, fail with disambiguation request

• Merge conflict rule:

- Objective/scope conflicts between primary and supplemental sources are blocking and require user clarification.

Skill Dependencies

Document Type Contract (MANDATORY)

When generating TSPEC document instances, the autopilot MUST:

1. Read instance_document_type from template:

- Source: ai_dev_ssd_flow/10_TSPEC/TSPEC-MVP-TEMPLATE.yaml - Field: metadata.instance_document_type: "tspec-document"

1. Set document_type in generated document frontmatter: custom_fields: document_type: tspec-document # NOT "template" artifact_type: TSPEC layer: 10
2. Validation: Generated documents MUST have document_type: tspec-document

- Templates have document_type: template - Instances have document_type: tspec-document - Schema validates both values

Error Handling: If instance_document_type is missing from template, default to tspec-document.

Smart Document Detection

The autopilot automatically determines the action based on the input document type.

Input Type Recognition

Detection Algorithm

1. Parse input: Extract TYPE and NN from "{TYPE}-{NN}"
2. Determine action:
   - IF TYPE == "TSPEC": Review Mode
   - ELSE IF TYPE == "SPEC": Generate/Find Mode
   - ELSE: Error (invalid type for this autopilot)
3. For Generate/Find Mode:
   - Check: Does TSPEC-{NN} exist in docs/10_TSPEC/?
   - IF exists: Switch to Review Mode for TSPEC-{NN}
   - ELSE: Proceed with Generation from SPEC-{NN}

File Existence Check

# Check for nested folder structure (mandatory)
ls docs/10_TSPEC/TSPEC-{NN}_*/

Examples

# Review mode (same type - TSPEC input)
/doc-tspec-autopilot TSPEC-01        # Reviews existing TSPEC-01

# Generate/Find mode (upstream type - SPEC input)
/doc-tspec-autopilot SPEC-01         # Generates TSPEC-01 if missing, or reviews existing TSPEC-01

# Multiple inputs
/doc-tspec-autopilot SPEC-01,SPEC-02 # Generates/reviews TSPEC-01 and TSPEC-02
/doc-tspec-autopilot TSPEC-01,TSPEC-02 # Reviews TSPEC-01 and TSPEC-02

Action Determination Output

Input: SPEC-01
├── Detected Type: SPEC (upstream)
├── Expected TSPEC: TSPEC-01
├── TSPEC Exists: Yes → docs/10_TSPEC/TSPEC-01_f1_iam/
└── Action: REVIEW MODE - Running doc-tspec-reviewer on TSPEC-01

Input: SPEC-05
├── Detected Type: SPEC (upstream)
├── Expected TSPEC: TSPEC-05
├── TSPEC Exists: No
└── Action: GENERATE MODE - Creating TSPEC-05 from SPEC-05

Input: TSPEC-03
├── Detected Type: TSPEC (self)
└── Action: REVIEW MODE - Running doc-tspec-reviewer on TSPEC-03

Workflow Overview

flowchart TD
    subgraph Phase1["Phase 1: SPEC Analysis"]
        A[Start] --> B[Read SPEC Documents]
        B --> C[Extract Methods]
        C --> D[Extract Interfaces]
        D --> E[Extract Data Models]
        E --> F[Catalog Test Targets]
    end

    subgraph Phase2["Phase 2: Test Coverage Planning"]
        F --> G[Check SPEC TASKS-Ready Score]
        G --> H{Score >= 90%?}
        H -->|No| I[Flag SPEC Issues]
        I --> J{Auto-Fixable?}
        J -->|Yes| K[Fix SPEC Issues]
        K --> G
        J -->|No| L[Abort - Manual Fix Required]
        H -->|Yes| M[Plan Test Coverage]
        M --> N[Allocate Test Types]
    end

    subgraph Phase3["Phase 3: TSPEC Generation"]
        N --> O[Generate UTEST Specs]
        O --> P[Generate ITEST Specs]
        P --> Q[Generate STEST Specs]
        Q --> R[Generate FTEST Specs]
        R --> S[quality-advisor: Real-time Feedback]
        S --> T[Build Coverage Matrix]
        T --> U[Add Traceability Tags]
        U --> V[Write TSPEC Files]
    end

    subgraph Phase4["Phase 4: TSPEC Validation"]
        V --> W[Run doc-tspec-validator]
        W --> X{TASKS-Ready >= 90%?}
        X -->|No| Y[Auto-Fix TSPEC Issues]
        Y --> Z[Re-validate TSPEC]
        Z --> X
        X -->|Yes| AA[Mark TSPEC Validated]
    end

    subgraph Phase5["Phase 5: Review & Fix Cycle"]
        AA --> AB[Run doc-tspec-reviewer]
        AB --> AB2{Score >= 90?}
        AB2 -->|No| AB3[Run doc-tspec-fixer]
        AB3 --> AB4{Iteration < Max?}
        AB4 -->|Yes| AB
        AB4 -->|No| AB5[Flag Manual Review]
        AB2 -->|Yes| AC[Verify Quality Checks]
        AB5 --> AC
        AC --> AD[Update Traceability Matrix]
        AD --> AE[Generate Summary Report]
    end

    AE --> AF[Complete]
    L --> AG[Exit with Error]

Test Types

TSPEC Structure

All TSPEC use nested folders (TSPEC-NN_{slug}/). This keeps test specification files and companion files organized together.

docs/10_TSPEC/
├── TSPEC-01_authentication/
│   ├── TSPEC-01.md              # Suite index
│   ├── TSPEC-01.1_utest.md              # Unit tests
│   ├── TSPEC-01.2_itest.md              # Integration tests
│   ├── TSPEC-01.3_stest.md              # Smoke tests
│   ├── TSPEC-01.4_ftest.md              # Functional tests
│   ├── TSPEC-01.A_audit_report_v001.md  # Combined audit report (preferred)
│   ├── TSPEC-01.R_review_report_v001.md # Review report (legacy-compatible)
│   ├── TSPEC-01.F_fix_report_v001.md    # Fix report
│   └── .drift_cache.json                 # Drift cache
└── TSPEC-01_authentication.md            # Redirect stub (optional)

Coverage Matrix Format

Element ID Format

Phase 5: Review & Fix Cycle (v2.3)

Iterative review and fix cycle to ensure TSPEC quality before completion.

flowchart TD
  A[Phase 5 Start] --> B[Run doc-tspec-audit]
  B --> C[Generate Combined Audit Report]
  C --> D{Audit PASS and score >= 90?}

    D -->|Yes| E[PASS - Proceed to Phase 6]
    D -->|No| F{Iteration < Max?}

    F -->|Yes| G[Run doc-tspec-fixer]
    G --> H[Apply Fixes]
    H --> I[Generate Fix Report]
    I --> J[Increment Iteration]
    J --> B

    F -->|No| K[Flag for Manual Review]
    K --> L[Generate Final Report with Remaining Issues]
    L --> E

5.1 Initial Review

Run doc-tspec-audit to perform validator+reviewer checks and produce a unified fixer-ready report.

/doc-tspec-audit TSPEC-NN

Output: TSPEC-NN.A_audit_report_v001.md (preferred), with .R_review_report_vNNN.md compatibility preserved.

5.2 Fix Cycle

If review score < 90%, invoke doc-tspec-fixer.

/doc-tspec-fixer TSPEC-NN --revalidate

Fix Categories:

Output: TSPEC-NN.F_fix_report_v001.md

5.3 Re-Review

After fixes, automatically re-run audit.

/doc-tspec-audit TSPEC-NN

Output: TSPEC-NN.A_audit_report_v002.md (preferred), with legacy .R_ compatibility.

5.4 Iteration Control

Iteration Example:

Iteration 1:
  Review v001: Score 78 (2 errors, 6 warnings)
  Fix v001: Fixed 5 issues, created 1 test file

Iteration 2:
  Review v002: Score 91 (0 errors, 2 warnings)
  Status: PASS (score >= 90)

5.5 Quality Checks (Post-Fix)

After passing the fix cycle:

1. Test Type Completeness:

- All 4 test types present (UTEST, ITEST, STEST, FTEST) - Each test type file has required sections - No placeholder text remaining

1. Coverage Matrix Accuracy:

- All SPEC elements have test coverage - Coverage percentages calculated correctly - Target coverage met per test type

1. Element ID Compliance (per doc-naming skill):

- All IDs use TSPEC.NN.xxxx format - Element type codes valid for TSPEC (40, 41, 42, 43) - No legacy patterns (UT-XXX, IT-XXX, ST-XXX, FT-XXX)

1. TASKS-Ready Report: TASKS-Ready Score Breakdown =========================== Test Type Completeness: 25/25 (all 4 types present) Coverage Matrix: 18/20 (coverage targets met) SPEC Alignment: 20/20 (tests trace to SPEC) Element ID Format: 15/15 (valid format) Traceability Tags: 10/10 (8 required tags) Test Assertions: 8/10 (assertions present) ---------------------------- Total TASKS-Ready Score: 96/100 (Target: >= 90) Status: READY FOR TASKS GENERATION
2. Traceability Matrix Update: # Update TSPEC traceability

python ai_dev_ssd_flow/scripts/update_traceability_matrix.py --tspec docs/10_TSPEC/TSPEC-NN_{slug}/ --matrix docs/10_TSPEC/TSPEC-00_TRACEABILITY_MATRIX.md

---

## Cumulative Tags (8 Required)

@brd: BRD.NN.xxxx @prd: PRD.NN.xxxx @ears: EARS.NN.xxxx @bdd: BDD.NN.xxxx @adr: ADR-NN @sys: SYS.NN.xxxx @req: REQ.NN.xxxx @spec: SPEC-NN @ctr: CTR.NN.xxxx # Optional

---

## Configuration

### Default Configuration

tspec_autopilot: version: "1.0"

scoring: tasks_ready_min: 90 strict_mode: false

execution: max_parallel: 3 # HARD LIMIT - do not exceed chunk_size: 3 # Documents per chunk pause_between_chunks: true auto_fix: true continue_on_error: false timeout_per_spec: 180 # seconds

output: structure: sectioned # 4 test type files per TSPEC report_format: markdown

validation: skip_validation: false fix_iterations_max: 3

test_types: utest: true itest: true stest: true ftest: true

---

## Execution Modes

### Mode 1: Generate Mode (Default)

Standard TSPEC generation from SPEC documents (see Workflow Overview above).

### Mode 2: Review Mode (v2.1)

Validate existing TSPEC documents without modification. Generates quality report with actionable recommendations.

**Command**:

Review single TSPEC

/doc-tspec-autopilot TSPEC-01 --review

Review all TSPEC in directory

/doc-tspec-autopilot docs/10_TSPEC/ --review --all

Review with detailed report

/doc-tspec-autopilot TSPEC-01 --review --verbose

**Review Process**:

flowchart TD A[Input: TSPEC Document] --> B[Load TSPEC Content] B --> C[Validate Test Structure] C --> D[Check TASKS-Ready Score] D --> E[Verify All 4 Test Types] E --> F[Validate Coverage Matrix] F --> G[Check Element IDs] G --> H[Verify Cumulative Tags] H --> I[Generate Review Report] I --> J{Issues Found?} J -->|Yes| K[Categorize Issues] K --> L[Generate Fix Recommendations] L --> M[Output Review Report] J -->|No| M

**Review Report Template**:

TSPEC Review Report: TSPEC-NN_{slug}

Summary

• TASKS-Ready Score: NN% (✅/🟡/❌)
• Total Issues: N (E errors, W warnings)
• Auto-Fixable: N issues
• Manual Review: N issues

Test Type Coverage

Score Breakdown

Issues by Category

Auto-Fixable Issues

Manual Review Required

**Score Indicators**:

- ✅ Green (>=90%): TASKS-Ready
- 🟡 Yellow (70-89%): Needs improvement
- ❌ Red (<70%): Significant issues

**Review Configuration**:

review_mode: enabled: true checks: - test_structure # All 4 test type files present - coverage_matrix # Coverage >= target per SPEC element - spec_alignment # Tests trace to SPEC methods - element_ids # TSPEC.NN.40-43.SS format - cumulative_tags # 8 required tags present - test_assertions # Each test has clear assertions output: format: markdown # markdown, json, html include_recommendations: true include_fix_commands: true coverage_targets: utest: 95 # Unit test coverage target % itest: 85 # Integration test coverage target % stest: 100 # Smoke test must cover critical path ftest: 75 # Functional test coverage target %

### Mode 3: Fix Mode (v2.1)

Auto-repair existing TSPEC documents with backup and content preservation.

**Command**:

Fix single TSPEC

/doc-tspec-autopilot TSPEC-01 --fix

Fix with backup

/doc-tspec-autopilot TSPEC-01 --fix --backup

Fix all TSPEC

/doc-tspec-autopilot docs/10_TSPEC/ --fix --all

Fix specific categories only

/doc-tspec-autopilot TSPEC-01 --fix --only element_ids,tags

Dry-run fix (preview changes)

/doc-tspec-autopilot TSPEC-01 --fix --dry-run

**Fix Process**:

flowchart TD A[Input: TSPEC Document] --> B[Create Backup] B --> C[Load TSPEC Content] C --> D[Run Review Analysis] D --> E{Auto-Fixable Issues?} E -->|No| F[Report: No Fixes Needed] E -->|Yes| G[Apply Fixes by Category]

subgraph FixCategories["Fix Categories"] G --> H[Fix Element IDs] H --> I[Fix Test Type Structure] I --> J[Regenerate Coverage Matrix] J --> K[Add Missing Tags] K --> L[Fix Section Structure] L --> M[Add Missing Test Stubs] end

M --> N[Validate Fixed Document] N --> O{Validation Passed?} O -->|No| P[Rollback to Backup] P --> Q[Report: Fix Failed] O -->|Yes| R[Save Fixed Document] R --> S[Generate Fix Report]

**TSPEC-Specific Fix Categories**:

| Category | Description | Auto-Fix Actions |
| --- | --- | --- |
| `element_ids` | Element ID format | Convert legacy patterns to TSPEC.NN.xxxx |
| `test_types` | Test type files | Create missing UTEST/ITEST/STEST/FTEST files |
| `coverage_matrix` | Coverage tracking | Regenerate matrix from test specifications |
| `cumulative_tags` | Traceability tags | Add missing 8 upstream tags |
| `sections` | Section structure | Add missing sections per test type template |
| `test_stubs` | Missing tests | Generate test stubs for uncovered SPEC elements |
| `assertions` | Test assertions | Flag tests without assertions (manual fix) |

**Element ID Migration** (Layer 10):

| Legacy Pattern | New Format | Example |
| --- | --- | --- |
| UT-NNN | TSPEC.NN.40.SS | UT-001 → TSPEC.01.4001 |
| IT-NNN | TSPEC.NN.41.SS | IT-001 → TSPEC.01.4101 |
| ST-NNN | TSPEC.NN.42.SS | ST-001 → TSPEC.01.4201 |
| FT-NNN | TSPEC.NN.43.SS | FT-001 → TSPEC.01.4301 |
| TC-NNN | TSPEC.NN.40.SS | TC-001 → TSPEC.01.4001 (assume UTEST) |
| TEST-NNN | TSPEC.NN.43.SS | TEST-001 → TSPEC.01.4301 (assume FTEST) |

**Content Preservation Rules**:

| Content Type | Preservation Rule |
| --- | --- |
| Custom test descriptions | Never delete, only enhance metadata |
| Test assertions | Preserve all test logic |
| Test data/fixtures | Preserve all test data definitions |
| SPEC references | Validate and update format only |
| Coverage percentages | Recalculate after fixes |
| Test prerequisites | Preserve setup/teardown logic |

**Fix Configuration**:

fix_mode: enabled: true backup: enabled: true location: "tmp/backups/" timestamp: true fix_categories: element_ids: true # Convert legacy ID patterns test_types: true # Create missing test type files coverage_matrix: true # Regenerate coverage tracking cumulative_tags: true # Add 8 required tags sections: true # Add missing sections test_stubs: true # Generate stubs for uncovered SPEC assertions: false # Manual only (flag but don't auto-fix) validation: post_fix: true # Validate after fixes rollback_on_fail: true # Restore backup if validation fails preserve: test_descriptions: true test_assertions: true test_data: true spec_references: true

**Fix Report Template**:

TSPEC Fix Report: TSPEC-NN_{slug}

Summary

• Backup Created: tmp/backups/TSPEC-NN_{slug}_20260209_143022/
• Issues Fixed: N of M auto-fixable issues
• Manual Review: N issues flagged

Fixes Applied

Element ID Migration

Test Type Files Created

Coverage Matrix Regenerated

Cumulative Tags Added

• @ears: EARS.01.25001 (added)
• @sys: SYS.01.0101 (added)
• @req: REQ.01.0101 (added)

Test Stubs Generated

Manual Review Required

Tests Without Assertions

Low Coverage Areas

Validation Results

• TASKS-Ready Score: Before: 68% → After: 92%
• Validation Errors: Before: 12 → After: 0
• Status: ✅ All auto-fixes validated

**Command Line Options** (Review/Fix Modes):

| Option | Default | Description |
| --- | --- | --- |
| `--review` | false | Run review mode only |
| `--fix` | false | Run fix mode |
| `--backup` | true | Create backup before fixing |
| `--dry-run` | false | Preview fixes without applying |
| `--only` | all | Comma-separated fix categories |
| `--verbose` | false | Detailed output |
| `--all` | false | Process all TSPEC in directory |
| `--output-format` | markdown | Report format (markdown, json) |
| `--generate-stubs` | true | Generate test stubs for uncovered SPEC |
| `--test-types` | all | Comma-separated test types to fix |

---

## Context Management

### Chunked Parallel Execution (MANDATORY)

**CRITICAL**: To prevent conversation context overflow errors ("Prompt is too long", "Conversation too long"), all autopilot operations MUST follow chunked execution rules:

**Chunk Size Limit**: Maximum 3 documents per chunk

**Chunking Rules**:

1. **Chunk Formation**: Group SPEC-derived TSPEC documents into chunks of maximum 3 at a time
2. **Sequential Chunk Processing**: Process one chunk at a time, completing all documents in a chunk before starting the next
3. **Context Pause**: After completing each chunk, provide a summary and pause for user acknowledgment
4. **Progress Tracking**: Display chunk progress (e.g., "Chunk 2/4: Processing TSPEC-04, TSPEC-05, TSPEC-06...")

**Why Chunking is Required**:

- Prevents "Conversation too long" errors during batch processing
- Allows context compaction between chunks
- Enables recovery from failures without losing all progress
- Provides natural checkpoints for user review

**Chunk Completion Template**:

Chunk N/M Complete

Generated:

• TSPEC-XX: TASKS-Ready Score 94% (UTEST + ITEST + STEST + FTEST)
• TSPEC-YY: TASKS-Ready Score 92% (UTEST + ITEST + STEST + FTEST)
• TSPEC-ZZ: TASKS-Ready Score 95% (UTEST + ITEST + STEST + FTEST)

Proceeding to next chunk...

---

## Related Resources

- **TSPEC Skill**: `.claude/skills/doc-tspec/SKILL.md`
- **TSPEC Validator**: `.claude/skills/doc-tspec-validator/SKILL.md`
- **Naming Standards**: `.claude/skills/doc-naming/SKILL.md`
- **Quality Advisor**: `.claude/skills/quality-advisor/SKILL.md`
- **TSPEC Template**: `ai_dev_ssd_flow/10_TSPEC/TSPEC-MVP-TEMPLATE.md`

---

## Review Document Standards (v2.2)

Review reports generated by this skill are formal project documents and MUST comply with shared standards.

**Reference**: See `REVIEW_DOCUMENT_STANDARDS.md` in the skills directory for complete requirements.

**Key Requirements**:

1. **Storage Location**: Same folder as the reviewed TSPEC document
2. **File Naming**: `TSPEC-NN.A_audit_report_vNNN.md` (preferred) and `TSPEC-NN.R_review_report_vNNN.md` (legacy-compatible)
3. **YAML Frontmatter**: Required with `artifact_type: TSPEC-REVIEW`, `layer: 10`
4. **Score Field**: `impl_ready_score_claimed` / `impl_ready_score_validated`
5. **Parent Reference**: Must link to parent TSPEC document

**Example Location** (ALWAYS use nested folders):

docs/10_TSPEC/TSPEC-03_f3_observability/ ├── TSPEC-03_f3_observability.md # ← Main document ├── TSPEC-03.A_audit_report_v001.md # ← Combined audit report (preferred) ├── TSPEC-03.R_review_report_v001.md # ← Review report ├── TSPEC-03.F_fix_report_v001.md # ← Fix report └── .drift_cache.json # ← Drift cache

**Nested Folder Rule**: ALL TSPEC use nested folders (`TSPEC-NN_{slug}/`) regardless of size. This keeps companion files (review reports, fix reports, drift cache) organized with their parent document.

---

## Version History

| Version | Date | Changes |
| --- | --- | --- |
| 2.6 | 2026-02-27 | Normalized frontmatter to `metadata` schema with `versioning_policy`; integrated `doc-tspec-audit` audit-first workflow and outputs; updated stale traceability command path to `ai_dev_ssd_flow/scripts/update_traceability_matrix.py`; normalized review-document naming guidance to versioned `.A_` preferred with `.R_` legacy compatibility |
| 2.5 | 2026-02-26 | Added PTEST (code 44) and SECTEST (code 45) support in test types and element ID tables; Fixed template path to ai_dev_ssd_flow/10_TSPEC/TSPEC-MVP-TEMPLATE.md; Fixed @spec tag format to use dash notation (SPEC-NN) |
| 2.4 | 2026-02-11 | **Smart Document Detection**: Added automatic document type recognition; Self-type input (TSPEC-NN) triggers review mode; Upstream-type input (SPEC-NN) triggers generate-if-missing or find-and-review; Updated input patterns table with type-based actions |
| 2.3 | 2026-02-10 | **Review & Fix Cycle**: Replaced Phase 5 with iterative Review -> Fix cycle using `doc-tspec-reviewer` and `doc-tspec-fixer`; Added `doc-tspec-fixer` skill dependency; Added iteration control (max 3 cycles); Added quality checks (test type completeness, coverage matrix accuracy, element ID compliance, TASKS-Ready report); Added traceability matrix update step |
| 2.2 | 2026-02-10 | Added Review Document Standards section; Review reports now stored alongside reviewed documents with proper YAML frontmatter and parent references |
| 2.1 | 2026-02-09 | Added Mode 2: Review Mode for validation-only analysis with visual score indicators and coverage targets; Added Mode 3: Fix Mode for auto-repair with backup, content preservation, and test stub generation; Element ID migration (UT-NNN→TSPEC.NN.40.SS, IT-NNN→TSPEC.NN.41.SS, ST-NNN→TSPEC.NN.42.SS, FT-NNN→TSPEC.NN.43.SS) |
| 1.0 | 2026-02-08 | Initial skill creation with 5-phase workflow; Integrated doc-naming, doc-tspec, quality-advisor, doc-tspec-validator; Support for all 4 test types |