doc-sys-autopilot（文档系统自动驾驶仪）

doc-sys-autopilot

Purpose

Automated System Requirements (SYS) generation pipeline that processes ADR architecture decisions to generate comprehensive system requirements documents with functional requirements, quality attributes, and REQ-Ready scoring.

Layer: 6 (System Requirements)

Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5)

Downstream Artifacts: REQ (Layer 7)

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

This autopilot orchestrates the following skills:

Delegation Principle: The autopilot orchestrates workflow but delegates:

• SYS structure/content rules -> doc-sys skill
• Real-time quality feedback -> quality-advisor skill
• SYS validation logic -> doc-sys-validator skill
• Content review and scoring -> doc-sys-reviewer skill
• Issue resolution and fixes -> doc-sys-fixer skill
• Element ID standards -> doc-naming skill

Document Type Contract (MANDATORY)

When generating SYS document instances, the autopilot MUST:

1. Read instance_document_type from template:

- Source: ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.yaml - Field: metadata.instance_document_type: "sys-document"

1. Set document_type in generated document frontmatter: custom_fields: document_type: sys-document # NOT "template" artifact_type: SYS layer: 6
2. Validation: Generated documents MUST have document_type: sys-document

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

Error Handling: If instance_document_type is missing from template, default to sys-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 == "SYS": Review Mode
   - ELSE IF TYPE == "ADR": Generate/Find Mode
   - ELSE: Error (invalid type for this autopilot)
3. For Generate/Find Mode:
   - Check: Does SYS-{NN} exist in docs/06_SYS/?
   - IF exists: Switch to Review Mode for SYS-{NN}
   - ELSE: Proceed with Generation from ADR-{NN}

File Existence Check

# Check for nested folder structure (mandatory)
ls docs/06_SYS/SYS-{NN}_*/

Examples

# Review mode (same type - SYS input)
/doc-sys-autopilot SYS-01           # Reviews existing SYS-01

# Generate/Find mode (upstream type - ADR input)
/doc-sys-autopilot ADR-01           # Generates SYS-01 if missing, or reviews existing SYS-01

# Multiple inputs
/doc-sys-autopilot ADR-01,ADR-02    # Generates/reviews SYS-01 and SYS-02
/doc-sys-autopilot SYS-01,SYS-02    # Reviews SYS-01 and SYS-02

Action Determination Output

Input: ADR-01
├── Detected Type: ADR (upstream)
├── Expected SYS: SYS-01
├── SYS Exists: Yes → docs/06_SYS/SYS-01_f1_iam/
└── Action: REVIEW MODE - Running doc-sys-reviewer on SYS-01

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

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

When to Use This Skill

Use doc-sys-autopilot when:

• ADR documents are complete with SYS-Ready score >= 90%
• Need to generate system requirements from architecture decisions
• Want automated functional requirement and quality attribute generation
• Ensuring consistent SYS quality across the project
• Automating SYS generation in CI/CD pipelines

Do NOT use when:

• Manually creating a single SYS with extensive customization (use doc-sys directly)
• ADR documents are incomplete or have SYS-Ready score < 90%
• Editing specific SYS sections (use doc-sys for guidance)
• Validating existing SYS only (use doc-sys-validator)

Workflow Overview

flowchart TD
    subgraph Phase1["Phase 1: ADR Analysis"]
        A[Start] --> B[Read ADR Documents]
        B --> C[Extract Architecture Decisions]
        C --> D[Identify System Constraints]
        D --> E[Catalog Technical Requirements]
    end

    subgraph Phase2["Phase 2: SYS Readiness Check"]
        E --> F[Check ADR SYS-Ready Scores]
        F --> G{All ADRs >= 90%?}
        G -->|No| H[Flag ADRs Below Threshold]
        H --> I[Report Missing Elements]
        I --> J[Abort or Continue with Warnings]
        G -->|Yes| K[Mark ADRs Ready for SYS]
    end

    subgraph Phase3["Phase 3: SYS Generation"]
        K --> L{Next ADR Topic}
        L --> M[Load SYS Template]
        M --> N[Generate Document Control]
        N --> O[Generate Functional Requirements]
        O --> P[Generate Quality Attributes]
        P --> Q[Generate Interface Specifications]
        Q --> R[quality-advisor: Real-time Feedback]
        R --> S[Generate Remaining Sections]
        S --> T[Add Cumulative Tags]
        T --> U[Write SYS Files]
    end

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

    subgraph Phase5["Phase 5: Review & Fix Cycle"]
        Z --> ZA[Run doc-sys-reviewer]
        ZA --> ZB{Score >= 90?}
        ZB -->|No| ZC[Run doc-sys-fixer]
        ZC --> ZD{Iteration < Max?}
        ZD -->|Yes| ZA
        ZD -->|No| ZE[Flag Manual Review]
        ZB -->|Yes| ZF[Verify Quality Checks]
        ZE --> ZF
        ZF --> AA{More ADR Topics?}
        AA -->|Yes| L
        AA -->|No| AB[Check All SYS Complete]
        AB --> AC[Verify Cross-SYS Consistency]
        AC --> AD[Update Traceability Matrix]
        AD --> AE[Generate Summary Report]
    end

    AE --> AF[Complete]

Detailed Workflow

Phase 1: ADR Analysis

Analyze ADR documents to extract architecture decisions and system constraints.

Input Sources:

Analysis Process:

# Locate ADR documents
find docs/05_ADR/ -name "ADR-*.md" -type f | sort

# Check for SYS-Ready scores in ADRs
grep -E "SYS-Ready.*Score" docs/05_ADR/ADR-*.md

Required ADR Content per Topic:

Output: System requirements catalog with ADR-derived constraints and technical requirements.

Phase 2: SYS Readiness Check

Validate that all ADR documents meet the SYS-Ready threshold before proceeding.

Skill Delegation: Element ID validation follows rules in doc-naming skill. See: .claude/skills/doc-naming/SKILL.md for element type codes.

SYS-Ready Score Requirements:

Minimum Score: 90%

ADR to SYS Mapping:

Readiness Check Process:

def check_adr_readiness(adr_list: list) -> dict:
    """
    Check SYS-Ready scores for all ADR documents.

    Returns:
        dict with 'ready' (list of ADRs >= 90%)
        and 'not_ready' (list of ADRs < 90% with issues)
    """
    ready = []
    not_ready = []

    for adr in adr_list:
        score = extract_sys_ready_score(adr)
        if score >= 90:
            ready.append(adr)
        else:
            not_ready.append({
                'adr': adr,
                'score': score,
                'issues': identify_missing_elements(adr)
            })

    return {'ready': ready, 'not_ready': not_ready}

Phase 3: SYS Generation

Generate SYS documents with functional requirements and quality attributes.

Skill Delegation: This phase follows rules defined in doc-sys skill. See: .claude/skills/doc-sys/SKILL.md for complete SYS creation guidance. Quality Guidance: Uses quality-advisor skill for real-time feedback during generation. See: .claude/skills/quality-advisor/SKILL.md for quality monitoring.

Generation Process:

1. Reserve SYS ID: # Check for next available ID ls docs/06_SYS/SYS-*.md 2>/dev/null | \ grep -oP 'SYS-\K\d+' | sort -n | tail -1 # Increment for new SYS
2. Load SYS Template:

• Primary: ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md
• Rules: ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md

1. Generate Document Control Section: Field Value Project Name From BRD Document Version 0.1.0 Date Created Current date (YYYY-MM-DD) Last Updated Current date (YYYY-MM-DD) Document Owner From ADR stakeholder analysis Prepared By AI Assistant Status Draft (or In Review if ADR Accepted) EARS-Ready Score From upstream EARS REQ-Ready Score Calculated after generation
2. Generate Functional Requirements (Part 2 - Section 4): From ADR Decision and Implementation sections: Element ID Requirement Priority Source Verification SYS.01.0101 The system shall... Must Have ADR-01.Decision Integration Test SYS.01.0102 The system shall... Should Have ADR-01.Impl Unit Test Element Type Codes (per doc-naming skill): Element Type Code Example Functional Requirement 01 SYS.02.0101 Quality Attribute 02 SYS.02.0201 Use Case 11 SYS.02.1101 System Requirement 26 SYS.02.2601
3. Generate Quality Attributes (Part 2 - Section 5): From ADR Consequences and Implementation sections: Required Categories: Category Source Metrics Performance ADR latency/throughput targets p50/p95/p99, TPS Reliability ADR availability/recovery Uptime %, MTBF, MTTR Scalability ADR scaling decisions Concurrent users, data volume Security ADR-04 Security ADR Auth latency, encryption Observability ADR-05 Observability ADR Log retention, alert thresholds Maintainability ADR deployment decisions Deploy frequency, coverage Quality Attribute Format: | ID | Category | Attribute | Target | Measurement | Source | |----|----------|-----------|--------|-------------|--------| | SYS.01.0201 | Performance | API Response Time | p95 < 100ms | APM Monitoring | @threshold: PRD.01.perf.api.p95_latency | | SYS.01.0202 | Reliability | Availability | 99.9% | Uptime Monitoring | @threshold: PRD.01.sla.uptime.target |
4. Generate Interface Specifications (Part 3 - Section 6): From ADR Integration decisions:

- External APIs (CTR-ready) - Internal interfaces - Data exchange protocols - Message formats

1. Real-Time Quality Feedback (via quality-advisor skill):

- Monitor section completion as content is generated - Detect anti-patterns (AP-001 to AP-017) during creation - Validate element ID format compliance (SYS.NN.xxxx) - Check for placeholder text ([TBD], TODO, XXX) - Verify Mermaid diagram presence (recommended for SYS) - Validate @threshold tag usage for quantitative values - Flag issues early to reduce post-generation rework

1. Generate Remaining Sections:

- Section 7: Data Management Requirements - Section 8: Testing and Validation Requirements - Section 9: Deployment and Operations Requirements - Section 10: Compliance and Regulatory Requirements - Section 11: Acceptance Criteria - Section 12: Risk Assessment - Section 13: Traceability - Section 14: Implementation Notes

1. Add Cumulative Tags (Section 13): Layer 6 Required Tags (5 tags): ## Traceability **Required Tags** (Cumulative Tagging Hierarchy - Layer 6): @brd: BRD.01.0103 @prd: PRD.01.0702, PRD.01.0715 @ears: EARS.01.2501, EARS.01.2502 @bdd: BDD.01.1401 @adr: ADR-01, ADR-04
2. File Output (ALWAYS use nested folder): Nested Folder Rule: ALL SYS use nested folders (SYS-NN_{slug}/) regardless of size. This keeps companion files (review reports, fix reports, drift cache) organized with their parent document.

- Monolithic (<20k tokens): docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md - Sectioned (≥20k tokens): docs/06_SYS/SYS-NN_{slug}/SYS-NN.0_index.md, SYS-NN.1_core.md, etc. - Modular (v2.0): docs/06_SYS/SYS-NN_{slug}/SYS-NN.MM_{capability}.md - Master Index (always): docs/06_SYS/SYS-00_index.md (create or update)

Modular Splitting Pattern (v2.0)

Per-Capability Decomposition

For complex SYS documents, split into atomic files per functional capability:

docs/06_SYS/SYS-01_f1_iam/
├── SYS-01.00_index.md                    # Index with REQ-Ready score
├── SYS-01.01_authentication.md           # Auth capabilities
├── SYS-01.02_authorization.md            # Authz capabilities
├── SYS-01.03_session_management.md       # Session handling
├── SYS-01.04_audit_logging.md            # Audit requirements
└── SYS-01.05_mfa_integration.md          # MFA requirements

Modular File Structure

Each modular SYS file contains:

Modular SYS Template

---
parent_doc: SYS-01
capability_id: SYS-01.01
capability_name: Authentication
version: 1.0.0
status: Draft
---

# SYS-01.01: Authentication

## Functional Requirements

| ID | Requirement | Priority | Source | Verification |
|----|-------------|----------|--------|--------------|
| SYS.01.0101 | The system SHALL authenticate users via JWT | Must Have | ADR-01 | Integration Test |
| SYS.01.0102 | The system SHALL validate tokens within @threshold:PRD.01.perf.auth.p95_latency | Must Have | ADR-01 | Performance Test |

## Quality Attributes

| ID | Category | Attribute | Target | Measurement |
|----|----------|-----------|--------|-------------|
| SYS.01.0201 | Performance | Auth latency | p95 < @threshold:PRD.01.perf.auth.p95_latency | APM |
| SYS.01.0202 | Reliability | Auth availability | @threshold:PRD.01.sla.auth.uptime | Uptime Monitor |

## External Dependencies

| Dependency | Type | Fallback Strategy | Timeout |
|------------|------|-------------------|---------|
| GCP Identity Platform | Infrastructure | Local JWT validation cache | @threshold:PRD.01.timeout.idp.max |
| Redis Session Store | Data | In-memory session cache | @threshold:PRD.01.timeout.redis.max |

## Traceability

@brd: BRD.01.0201
@prd: PRD.01.0701
@ears: EARS.01.2501
@bdd: BDD.01.1401
@adr: ADR-01

External Dependencies Table (v2.0)

Required Format

All SYS documents MUST include an External Dependencies table with fallback strategy:

Example External Dependencies Table

## External Dependencies

| Dependency | Type | Fallback Strategy | Timeout | Health Check |
|------------|------|-------------------|---------|--------------|
| GCP Identity Platform | infrastructure | JWT validation cache; fallback to local auth | @threshold:PRD.01.timeout.idp.max | /health/ready |
| Cloud SQL (PostgreSQL) | data | Read replica; local cache | @threshold:PRD.01.timeout.db.max | TCP check |
| Redis Cache | data | In-memory cache; proceed without | @threshold:PRD.01.timeout.cache.max | PING |
| Cloud Pub/Sub | integration | Retry with backoff; local queue | @threshold:PRD.01.timeout.pubsub.max | List topics |
| Cloud Secret Manager | security | Cached secrets; fail-safe defaults | @threshold:PRD.01.timeout.secrets.max | Access check |
| Cloud Monitoring | observability | Local metrics buffer; log to stdout | @threshold:PRD.01.timeout.monitoring.max | Write test |

Fallback Strategy Guidelines

6-Category REQ-Ready Scoring (v2.0)

Scoring Breakdown

Score Display Format

REQ-Ready Score: ✅ 94% (Target: ≥90%)

Category Breakdown:
├── Functional Decomposition:  24/25 ✅
├── Quality Attributes:        20/20 ✅
├── Interface Specifications:  18/20 🟡
├── Data Management:           14/15 ✅
├── Testing Requirements:       9/10 ✅
└── Traceability:              10/10 ✅

External Dependencies:
├── Dependencies Documented:   ✅ 6/6
├── Fallback Strategies:       ✅ 6/6
└── Threshold References:      ✅ 12/12

Visual Indicators

Phase 4: SYS Validation

After SYS generation, validate structure and REQ-Ready score.

Skill Delegation: This phase uses validation rules from doc-sys-validator skill. See: .claude/skills/doc-sys-validator/SKILL.md for complete validation rules.

Validation Command:

python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md --verbose

Validation Checks (14 Total for v2.0):

REQ-Ready Scoring Criteria (100%):

Minimum Score: 90%

Auto-Fix Actions:

Validation Loop:

LOOP (max 3 iterations):
  1. Run doc-sys-validator
  2. IF errors found: Apply auto-fixes
  3. IF warnings found: Review and address if critical
  4. IF REQ-Ready Score < 90%: Enhance sections
  5. IF clean: Mark VALIDATED, proceed
  6. IF max iterations: Log issues, flag for manual review

Phase 5: Audit & Fix Cycle (v2.1)

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

flowchart TD
  A[Phase 5 Start] --> B[Run doc-sys-audit]
  B --> C[Generate Combined Audit Report]
    C --> D{Review Score >= 90?}

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

    F -->|Yes| G[Run doc-sys-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 Audit

Run doc-sys-audit to identify issues.

/doc-sys-audit SYS-NN

Output: SYS-NN.A_audit_report_v001.md (legacy-compatible reviewer report may still exist)

5.2 Fix Cycle

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

/doc-sys-fixer SYS-NN --revalidate

Fix Categories:

Output: SYS-NN.F_fix_report_v001.md

5.3 Re-Audit

After fixes, automatically re-run audit.

/doc-sys-audit SYS-NN

Output: SYS-NN.A_audit_report_v002.md

5.4 Iteration Control

Iteration Example:

Iteration 1:
  Review v001: Score 86 (3 errors, 5 warnings)
  Fix v001: Fixed 6 issues, updated 2 tables

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

5.5 Quality Checks (Post-Fix)

After passing the fix cycle:

1. All SYS Complete:

- All ADR-derived system domains addressed - Each SYS has REQ-Ready score >= 90% - No placeholder text remaining - All @threshold tags reference valid registry entries

1. Cross-SYS Consistency:

- No conflicting requirements between SYS documents - Quality attribute targets align across systems - Interface specifications are compatible - Dependencies between SYS documented

1. Traceability Matrix Update: # Update SYS-00_TRACEABILITY_MATRIX.md

python ai_dev_ssd_flow/scripts/update_traceability_matrix.py --type SYS --matrix docs/06_SYS/SYS-00_TRACEABILITY_MATRIX.md

4. **REQ-Ready Report**:

REQ-Ready Score Breakdown

Functional Decomposition: 24/25 (System boundaries clear) Quality Attributes: 20/20 (All 6 categories present) Interface Specifications: 19/20 (CTR-ready) Data Management: 14/15 (Schemas documented) Testing Requirements: 9/10 (Coverage targets) Traceability: 10/10 (All 5 tags present)

Total REQ-Ready Score: 96/100 (Target: >= 90) Status: READY FOR REQ GENERATION

5. **Summary Report Generation**:

SYS Generation Summary

Total SYS Generated: 7

Status Distribution: Approved: 5 In Review: 2 Draft: 0

REQ-Ready Scores: SYS-01 (Infrastructure): 95% SYS-02 (Data Architecture): 92% SYS-03 (Integration): 94% SYS-04 (Security): 96% SYS-05 (Observability): 91% SYS-06 (AI/ML): 90% SYS-07 (Technology): 93%

Average REQ-Ready Score: 93%

Next Steps: 1. Review In Review SYS documents for stakeholder approval 2. Run doc-req-autopilot to decompose SYS into atomic REQ

---

## Execution Modes

### Single SYS Mode

Generate one SYS from a specific ADR.

Example: Generate SYS-01 from ADR-01

/doc-sys-autopilot ADR-01

Output:

Analyzing ADR-01 (Infrastructure)...

SYS-Ready Score: 94% (PASS)

Generating SYS-01_infrastructure.md...

REQ-Ready Score: 92%

Complete.

### Batch Mode (All ADRs)

Generate all SYS from ADR documents.

Example: Generate all SYS from ADR directory

/doc-sys-autopilot all

Output:

Scanning ADR directory...

Found 7 ADR documents:

ADR-01 (Infrastructure) - SYS-Ready: 94%

ADR-02 (Data Architecture) - SYS-Ready: 92%

ADR-03 (Integration) - SYS-Ready: 91%

ADR-04 (Security) - SYS-Ready: 95%

ADR-05 (Observability) - SYS-Ready: 90%

ADR-06 (AI/ML) - SYS-Ready: 91%

ADR-07 (Technology) - SYS-Ready: 93%

#

Generating SYS documents...

[================> ] 5/7 Complete

### Dry Run Mode

Preview SYS generation plan without creating files.

/doc-sys-autopilot all --dry-run

Output:

SYS Generation Plan (Dry Run)

============================

Source: ADR documents

#

Planned SYS:

1. SYS-01 (Infrastructure) - Full generation

2. SYS-02 (Data Architecture) - Full generation

3. SYS-03 (Integration) - Full generation

4. SYS-04 (Security) - Full generation

5. SYS-05 (Observability) - Full generation

6. SYS-06 (AI/ML) - Full generation

7. SYS-07 (Technology) - Full generation

#

No files will be created in dry-run mode.

### Review Mode (v2.1)

Validate existing SYS documents and generate a quality report without modification.

**Purpose**: Audit existing SYS documents for compliance, quality scores, and identify issues.

**Command**:

Review single SYS document

/doc-sys-audit SYS-01

Review all SYS documents (run per document in docs/06_SYS/)

/doc-sys-audit SYS-NN

**Review Process**:

flowchart TD A[Input: Existing SYS] --> B[Load SYS Documents] B --> C[Run Validation Checks] C --> D[Calculate REQ-Ready Score] D --> E[Check 6-Category Breakdown] E --> F[Validate External Dependencies] F --> G[Identify Issues] G --> H{Generate Report} H --> I[Fixable Issues List] H --> J[Manual Review Items] H --> K[Score Breakdown] I --> L[Output: Review Report] J --> L K --> L

**Review Report Structure**:

SYS Review Report: SYS-01_f1_iam

Summary

• REQ-Ready Score: 87% 🟡
• Total Issues: 14
• Auto-Fixable: 10
• Manual Review: 4

6-Category Score Breakdown

External Dependencies Check

v2.0 Compliance

Auto-Fixable Issues

Manual Review Required

Recommendations

1. Run fix mode to address 10 auto-fixable issues
2. Review 4 items requiring manual attention
3. Add missing external dependency fallback strategies

**Review Configuration**:

review_mode: enabled: true checks: - structure_validation # Document control, sections - element_id_compliance # SYS.NN.xxxx format - threshold_references # @threshold format and validity - external_dependencies # Table, fallback, timeouts - quality_attributes # 6 categories present - cumulative_tags # 5 upstream tags - score_calculation # REQ-Ready score - modular_structure # If >25KB output: format: markdown # markdown, json, html include_line_numbers: true include_fix_suggestions: true thresholds: pass: 90 warning: 85 fail: 0

### Fix Mode (v2.1)

Auto-repair existing SYS documents while preserving manual content.

**Purpose**: Apply automated fixes to SYS documents to improve quality scores and compliance.

**Command**:

Fix single SYS document

/doc-sys-fixer SYS-01

Fix with revalidation

/doc-sys-fixer SYS-01 --revalidate

Fix specific issue types only

/doc-sys-fixer SYS-01 --fix-types "element_ids,references,content"

Dry-run fix (preview changes)

/doc-sys-fixer SYS-01 --dry-run

**Fix Process**:

flowchart TD A[Input: Existing SYS] --> B[Run Review Mode] B --> C[Identify Fixable Issues] C --> D{Backup Enabled?} D -->|Yes| E[Create Backup] D -->|No| F[Skip Backup] E --> G[Apply Fixes by Category] F --> G

subgraph FixCategories["Fix Categories"] G --> H[Element ID Fixes] G --> I[Threshold Fixes] G --> J[Dependencies Fixes] G --> K[Structure Fixes] G --> L[Traceability Fixes] end

H --> M[Preserve Manual Content] I --> M J --> M K --> M L --> M

M --> N[Re-validate] N --> O{Score Improved?} O -->|Yes| P[Generate Fix Report] O -->|No| Q[Log Warnings] Q --> P P --> R[Output: Fixed SYS + Report]

**Fix Categories and Actions**:

| Category | Issue | Auto-Fix Action | Preserves Content |
| --- | --- | --- | --- |
| **Element IDs** | Legacy FR-XXX format | Convert to SYS.NN.01.SS | ✅ |
| **Element IDs** | Legacy QA-XXX format | Convert to SYS.NN.02.SS | ✅ |
| **Element IDs** | Invalid segment count | Restructure to 3-segment | ✅ |
| **Thresholds** | Hardcoded numeric values | Replace with @threshold:PRD.NN.xxx | ✅ |
| **Thresholds** | Invalid threshold format | Convert to @threshold:PRD.NN.category.field | ✅ |
| **Dependencies** | Missing fallback column | Add Fallback Strategy column | ✅ |
| **Dependencies** | Missing timeout @threshold | Add @threshold reference | ✅ |
| **Dependencies** | Missing health check | Add placeholder health check | ✅ |
| **Structure** | Missing REQ-Ready score | Calculate and insert | ✅ |
| **Structure** | Missing 6-category breakdown | Add breakdown table | ✅ |
| **Structure** | Missing traceability section | Insert from template | ✅ |
| **Traceability** | Missing cumulative tags | Add with placeholder references | ✅ |
| **Traceability** | Incomplete @adr reference | Link to source ADR | ✅ |

**Content Preservation Rules**:

1. **Never delete** existing functional requirements
2. **Never modify** quality attribute targets
3. **Never change** interface specification content
4. **Only add** missing columns and metadata
5. **Only replace** hardcoded values with threshold references
6. **Backup first** if `--backup` flag is set

**Fix Report Structure**:

SYS Fix Report: SYS-01_f1_iam

Summary

• Before REQ-Ready Score: 87% 🟡
• After REQ-Ready Score: 94% ✅
• Issues Fixed: 10
• Issues Remaining: 4 (manual review required)

Fixes Applied

Files Modified

• docs/06_SYS/SYS-01_f1_iam/SYS-01.00_index.md
• docs/06_SYS/SYS-01_f1_iam/SYS-01.01_authentication.md
• docs/06_SYS/SYS-01_f1_iam/SYS-01.02_authorization.md
• docs/06_SYS/SYS-01_f1_iam/SYS-01.03_session_management.md

Backup Location

• tmp/backup/SYS-01_f1_iam_20260209_143022/

Remaining Issues (Manual Review)

6-Category Score Impact

Next Steps

1. Review manually flagged items
2. Re-run validation to confirm score
3. Commit changes if satisfied

**Fix Configuration**:

fix_mode: enabled: true backup: enabled: true location: "tmp/backup/" retention_days: 7

fix_categories: element_ids: true # Legacy ID conversion thresholds: true # @threshold references dependencies: true # External dependencies table structure: true # Document sections traceability: true # Cumulative tags

preservation: functional_requirements: true # Never modify FR content quality_attributes: true # Never modify QA targets interface_specs: true # Never modify interface content comments: true # Preserve user comments

validation: re_validate_after_fix: true require_score_improvement: false max_fix_iterations: 3

element_id_migration: FR_XXX_to_SYS_NN_xxxx: true # FR-001 → SYS.01.0101 QA_XXX_to_SYS_NN_02_SS: true # QA-001 → SYS.01.0201 SR_XXX_to_SYS_NN_26_SS: true # SR-001 → SYS.01.2601

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

| Option | Mode | Default | Description |
| --- | --- | --- | --- |
| `--mode review` | Review | - | Run review mode only |
| `--mode fix` | Fix | - | Run fix mode |
| `--output-report` | Both | auto | Report output path |
| `--backup` | Fix | true | Create backup before fixing |
| `--fix-types` | Fix | all | Comma-separated fix categories |
| `--dry-run` | Fix | false | Preview fixes without applying |
| `--preserve-all` | Fix | false | Extra cautious preservation |
| `--min-score-gain` | Fix | 0 | Minimum score improvement required |

---

## Output Artifacts

### Generated Files

**All SYS use nested folders** (`SYS-NN_{slug}/`) regardless of size. Document sectioning (monolithic vs sectioned) depends only on document size (>20k tokens = sectioned).

| File | Purpose | Location |
| --- | --- | --- |
| SYS-NN_{slug}/ | SYS folder (ALWAYS created) | `docs/06_SYS/` |
| SYS-NN_{slug}.md | Main SYS document (monolithic <20k tokens) | `docs/06_SYS/SYS-NN_{slug}/` |
| SYS-NN.0_index.md | Section index (sectioned ≥20k tokens) | `docs/06_SYS/SYS-NN_{slug}/` |
| SYS-NN.S_{section}.md | Section files (sectioned ≥20k tokens) | `docs/06_SYS/SYS-NN_{slug}/` |
| SYS-NN.A_audit_report_v{VVV}.md | Combined audit report (preferred) | `docs/06_SYS/SYS-NN_{slug}/` |
| SYS-NN.R_review_report_v{VVV}.md | Review report | `docs/06_SYS/SYS-NN_{slug}/` |
| SYS-NN.F_fix_report_v{VVV}.md | Fix report | `docs/06_SYS/SYS-NN_{slug}/` |
| .drift_cache.json | Drift detection cache | `docs/06_SYS/SYS-NN_{slug}/` |

### Validation Reports

| Report | Purpose | Location |
| --- | --- | --- |
| sys_validation_report.json | Validation results | `tmp/` |
| req_ready_scores.json | REQ-Ready breakdown | `tmp/` |
| sys_autopilot_log.md | Execution log | `tmp/` |

---

## Error Handling

### Error Categories

| Category | Handling | Example |
| --- | --- | --- |
| ADR SYS-Ready < 90% | Abort with message | ADR-01 score at 85% |
| ADR Not Found | Skip or abort | ADR-08 does not exist |
| Validation Failure | Auto-fix, retry | Missing required section |
| REQ-Ready Below 90% | Enhance sections, retry | Score at 88% |
| Max Retries Exceeded | Flag for manual review | Persistent validation errors |

### Recovery Actions

def handle_error(error_type: str, context: dict) -> Action: match error_type: case "ADR_SYS_READY_LOW": return Action.ABORT_WITH_MESSAGE case "ADR_NOT_FOUND": return Action.SKIP_OR_ABORT case "VALIDATION_FAILURE": if context["retry_count"] < 3: return Action.AUTO_FIX_RETRY return Action.FLAG_MANUAL_REVIEW case "REQ_READY_LOW": return Action.ENHANCE_SECTIONS case _: return Action.FLAG_MANUAL_REVIEW

---

## Configuration

### Default Configuration

config/sys_autopilot.yaml

sys_autopilot: version: "2.0"

scoring: sys_ready_min: 90 # ADR threshold req_ready_min: 90 # SYS output threshold strict_mode: false # NEW: Visual score indicators score_display: pass_icon: "✅" # >= 90% warning_icon: "🟡" # 85-89% fail_icon: "❌" # < 85% # NEW: 6-category scoring weights scoring_weights: functional_decomposition: 25 quality_attributes: 20 interface_specifications: 20 data_management: 15 testing_requirements: 10 traceability: 10

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_adr: 180 # seconds

output: structure: auto # auto, monolithic, sectioned, modular size_threshold_kb: 25 report_format: markdown # NEW: Modular splitting options modular_splitting: enabled: true strategy: per_capability # per_capability, per_section max_file_size_kb: 50

validation: skip_validation: false fix_iterations_max: 3 require_threshold_tags: true # NEW: Enhanced validation checks require_external_dependencies: true require_fallback_strategy: true require_6_category_coverage: true

quality_attributes: require_performance: true require_reliability: true require_security: true require_scalability: false require_observability: true require_maintainability: false

# NEW: External Dependencies Configuration external_dependencies: require_table: true require_fallback: true categories: - infrastructure # GCP, AWS, Azure - data # Databases, caches - integration # APIs, message queues - security # Identity providers - observability # Monitoring, logging

### Command Line Options

| Option | Default | Description |
| --- | --- | --- |
| `--min-sys-ready` | 90 | Minimum ADR SYS-Ready score |
| `--min-req-ready` | 90 | Minimum SYS REQ-Ready score |
| `--no-auto-fix` | false | Disable auto-fix (manual only) |
| `--continue-on-error` | false | Continue if one ADR fails |
| `--dry-run` | false | Preview execution plan only |
| `--output-format` | auto | Force monolithic or sectioned output |
| `--skip-validation` | false | Skip validation phase |

---

## 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 ADR-derived SYS 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/3: Processing SYS-04, SYS-05, SYS-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

**Execution Pattern**:

For SYS batch of 7 ADR-derived documents: Chunk 1: SYS-01, SYS-02, SYS-03 → Complete → Summary [Context compaction opportunity] Chunk 2: SYS-04, SYS-05, SYS-06 → Complete → Summary [Context compaction opportunity] Chunk 3: SYS-07 → Complete → Summary

**Chunk Completion Template**:

Chunk N/M Complete

Generated:

• SYS-XX (Infrastructure): REQ-Ready Score 94%
• SYS-YY (Data Architecture): REQ-Ready Score 92%
• SYS-ZZ (Integration): REQ-Ready Score 95%

Proceeding to next chunk...

---

## Integration Points

### Pre-Execution Hooks

Hook: pre_sys_generation

Runs before SYS generation starts

./hooks/pre_sys_generation.sh

Example: Verify ADR SYS-Ready scores

for adr in docs/05_ADR/ADR-*.md; do score=$(grep -oP 'SYS-Ready.*\K\d+' "$adr") if [ "$score" -lt 90 ]; then echo "ERROR: $adr SYS-Ready score below 90%" exit 1 fi done

### Post-Execution Hooks

Hook: post_sys_generation

Runs after SYS generation completes

./hooks/post_sys_generation.sh

Example: Trigger REQ autopilot for validated SYS

if [ "$ALL_SYS_VALIDATED" = "true" ]; then /doc-req-autopilot all fi

### CI/CD Integration

.github/workflows/sys_autopilot.yml

name: SYS Autopilot

on: push: paths: - 'docs/05_ADR/**/ADR-*.md'

jobs: generate-sys: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

- name: Run SYS Autopilot run: | /doc-sys-autopilot all

- name: Upload Validation Report uses: actions/upload-artifact@v4 with: name: sys-validation path: tmp/sys_validation_report.json

---

## Quality Gates

### Phase Gates

| Phase | Gate | Criteria |
| --- | --- | --- |
| Phase 1 | ADR Gate | ADR documents exist with architecture decisions |
| Phase 2 | Readiness Gate | All ADRs have SYS-Ready score >= 90% |
| Phase 3 | Generation Gate | All 5 parts generated per system |
| Phase 4 | Validation Gate | REQ-Ready Score >= 90% |
| Phase 5 | Review Gate | No blocking issues remaining |

### Blocking vs Non-Blocking

| Issue Type | Blocking | Action |
| --- | --- | --- |
| Missing Functional Requirements | Yes | Must fix before proceeding |
| Missing Quality Attributes | Yes | Must fix before proceeding |
| REQ-Ready Score < 90% | Yes | Must enhance sections |
| Invalid element ID format | Yes | Must convert to unified format |
| Missing @threshold tags | Yes | Must add registry references |
| Hardcoded numeric values | Yes | Must replace with @threshold |
| Missing optional section | No | Log warning, continue |
| Style/formatting issues | No | Auto-fix, continue |

---

## Related Resources

- **SYS Creation Skill**: `.claude/skills/doc-sys/SKILL.md`
- **SYS Validator Skill**: `.claude/skills/doc-sys-validator/SKILL.md`
- **Quality Advisor Skill**: `.claude/skills/quality-advisor/SKILL.md`
- **Naming Standards Skill**: `.claude/skills/doc-naming/SKILL.md`
- **SYS Audit Skill**: `.claude/skills/doc-sys-audit/SKILL.md`
- **SYS Template**: `ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md`
- **SYS Creation Rules**: `ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md`
- **SYS Validation Rules**: `ai_dev_ssd_flow/06_SYS/SYS_MVP_SCHEMA.yaml`
- **ADR Autopilot Skill**: `.claude/skills/doc-adr-autopilot/SKILL.md`

---

## Quick Reference

| Input | Output | Key Metric |
| --- | --- | --- |
| ADR Documents | SYS-01 to SYS-07 | REQ-Ready >= 90% |

**Usage**:

/doc-sys-autopilot <ADR-ID|all> [OPTIONS]

**Common Commands**:

Generate all SYS from ADRs

/doc-sys-autopilot all

Generate single SYS from specific ADR

/doc-sys-autopilot ADR-01

Preview only

/doc-sys-autopilot all --dry-run

Resume after failure

/doc-sys-autopilot resume

**ADR to SYS Mapping**:

| ADR | SYS | System Domain |
| --- | --- | --- |
| ADR-01 | SYS-01 | Infrastructure |
| ADR-02 | SYS-02 | Data Architecture |
| ADR-03 | SYS-03 | Integration |
| ADR-04 | SYS-04 | Security |
| ADR-05 | SYS-05 | Observability |
| ADR-06 | SYS-06 | AI/ML |
| ADR-07 | SYS-07 | Technology Selection |

**Element ID Codes (SYS.NN.xxxx)**:

| Type | Code | Example |
| --- | --- | --- |
| Functional Requirement | 01 | SYS.02.0101 |
| Quality Attribute | 02 | SYS.02.0201 |
| Use Case | 11 | SYS.02.1101 |
| System Requirement | 26 | SYS.02.2601 |

**Cumulative Tags Required** (Layer 6 - 5 tags):

@brd: BRD.NN.xxxx @prd: PRD.NN.xxxx @ears: EARS.NN.xxxx @bdd: BDD.NN.xxxx @adr: ADR-NN

---

## Review Document Standards (v2.2)

**IMPORTANT**: Review reports generated by this autopilot are formal project documents.

See: `.claude/skills/REVIEW_DOCUMENT_STANDARDS.md` for complete standards.

### Quick Reference

| Requirement | Value |
| --- | --- |
| Storage Location | Same folder as reviewed SYS |
| File Name | `SYS-NN.A_audit_report_vNNN.md` (preferred), `SYS-NN.R_review_report_vNNN.md` (legacy) |
| YAML Frontmatter | MANDATORY - see shared standards |
| Parent Reference | MANDATORY - link to SYS document |

**Example Location**:

docs/06_SYS/ ├── SYS-03_f3_observability/ │ ├── SYS-03_f3_observability.md │ ├── SYS-03.A_audit_report_v001.md # ← Preferred report stored here │ └── SYS-03.R_review_report_v001.md # ← Legacy-compatible reviewer report

---

## Version History

| Version | Date | Changes |
| --- | --- | --- |
| 2.5 | 2026-02-27 | Migrated frontmatter to `metadata`; normalized SYS MVP references to `ai_dev_ssd_flow`; replaced non-existent direct script examples with skill invocation flow; aligned report contracts to prefer `SYS-NN.A_audit_report_vNNN.md` with legacy reviewer compatibility |
| 2.4 | 2026-02-11 | **Smart Document Detection**: Added automatic document type recognition; Self-type input (SYS-NN) triggers review mode; Upstream-type input (ADR-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-sys-reviewer` and `doc-sys-fixer`; Added `doc-sys-fixer` skill dependency; Phase 5 now includes flowchart, iteration control, and quality checks sections (5.1-5.5) |
| 2.2 | 2026-02-10 | Added Review Document Standards: review reports stored alongside reviewed documents with YAML frontmatter and parent references |
| 2.1 | 2026-02-09 | Added Review Mode for validating existing SYS documents without modification; Added Fix Mode for auto-repairing SYS documents while preserving manual content; Added fix categories (element_ids, thresholds, dependencies, structure, traceability); Added content preservation rules; Added backup functionality for fix operations; Added review/fix report generation with 6-category score impact; Added element ID migration support (FR_XXX, QA_XXX, SR_XXX to unified format) |
| 2.0 | 2026-02-09 | Added modular splitting pattern with per-capability decomposition; Added External Dependencies table with fallback strategy requirement; Added 6-category REQ-Ready scoring with weighted breakdown; Added visual score indicators (✅/🟡/❌); Added validation rules SYS-E040 to SYS-E045 for new features; Added modular SYS template for atomic files; Added fallback strategy guidelines by dependency type |
| 1.0 | 2026-02-08 | Initial skill creation with 5-phase workflow; Integrated doc-naming, doc-sys, doc-sys-validator, quality-advisor skills; Added ADR to SYS mapping; Functional requirements and quality attributes generation; REQ-Ready scoring |