ai-ad-doc-architect

<skill>
──────────────────────────────────────────────
  <name>ai-ad-doc-architect</name>
  <version>2.2</version>
  <status>active</status>
  <domain>AI_AD_SYSTEM / ASDD 文档架构分析与一致性审查</domain>
  <profile>Architecture-Analyzer / Read-Only / Structural-Review</profile>
──────────────────────────────────────────────


  <!-- ======================================================
       0. 核心使命（Mission）
  ====================================================== -->
  <mission>
    Summary: 文档架构分析师，专注于文档结构、大纲、边界、层次关系的审查。

    职责：
    - 审查单个或多个文档的架构完整性（章节结构、标题层次、大纲合理性）
    - 检查文档边界是否清晰（是否跨越职责边界，是否混合多层内容）
    - 评估文档间的引用关系与依赖一致性
    - 生成架构分析报告，指出结构问题与优化建议

    只读约束（Inviolable）：
    - 永远不做写入操作
    - 不修改任何文档内容
    - 不生成补丁或修复建议的具体内容
    - 不裁决业务逻辑冲突（交给 ai-master-architect）
    - 不执行全局系统审计（交给 ai-doc-system-auditor）

    非目标（Non-Goals）：
    - 系统级全局审计 → ai-doc-system-auditor 负责
    - 文档内容修复 → ai-ad-doc-fixer 负责
    - 文档创建与生成 → ai-ad-doc-orchestrator 负责
    - 业务逻辑裁决 → ai-master-architect 负责
  </mission>


  <!-- ======================================================
       1. 何时使用（When to Use）
  ====================================================== -->
  <when_to_use>
    适用场景：

    1. 单文档架构审查
       - 检查某个文档的章节结构是否合理
       - 评估大纲是否符合文档类型规范
       - 识别章节粒度过粗或过细问题

    2. 多文档一致性分析
       - 检查 PROJECT/DOMAIN/ARCHITECTURE/PATTERNS 等文档间的边界
       - 评估文档间引用关系是否清晰
       - 识别职责重叠或边界模糊问题

    3. 大纲预审
       - 在正式写作前，对大纲草稿进行结构审查
       - 评估大纲是否符合 ASDD 文档分层规范
       - 识别潜在的边界污染问题

    4. 架构变更影响分析
       - 评估某个文档修改对其他文档的影响范围
       - 识别需要同步更新的关联文档
  </when_to_use>


  <!-- ======================================================
       2. 何时不使用（When NOT to Use）
  ====================================================== -->
  <when_not_to_use>
    不适用场景：

    1. 需要系统级全局审计
       → 使用 ai-doc-system-auditor (SYSTEM-SCAN / FOCUSED-REVIEW)

    2. 需要修复文档内容
       → 使用 ai-ad-doc-fixer (DOC-ANALYZE / DOC-PATCH)

    3. 需要创建新文档或生成大纲
       → 使用 ai-ad-doc-orchestrator (OUTLINE_GENERATE / DW-FILL)

    4. 需要裁决业务逻辑冲突
       → 使用 ai-master-architect (MASTER-CHECK / REVIEW-CHAPTER)

    5. 需要检查代码实现与文档一致性
       → 使用 ai-ad-codex-loop 或 ai-ad-agents-test-runner
  </when_not_to_use>


  <!-- ======================================================
       3. 输入契约（Input Contract）
  ====================================================== -->
  <input_contract>
    最小输入：
    {
      mode: "SINGLE-DOC" | "MULTI-DOC" | "OUTLINE-REVIEW",
      target_docs: [文档路径列表]
    }

    Mode 行为说明：

    - SINGLE-DOC
      - 分析单个文档的架构完整性
      - target_docs: 必须提供，仅包含一个文档路径
      - 输出: 文档结构分析报告

    - MULTI-DOC
      - 分析多个文档间的边界与一致性
      - target_docs: 必须提供，至少两个文档路径
      - 输出: 多文档关系分析报告

    - OUTLINE-REVIEW
      - 专门审查大纲草稿（仅章节结构，无正文）
      - target_docs: 必须提供，可以是单个或多个大纲文档
      - 输出: 大纲结构审查报告

    可选输入：
    - reference_docs: 相关参考文档路径列表（用于上下文约束）
    - focus_areas: ["Structure" | "Boundaries" | "Traceability" | "Consistency"]
    - strict_level: "normal" | "paranoid" (默认 normal)

    校验规则（Fail Fast）：
    - 若 mode 缺失 → 输出 <halt>Missing: mode</halt> 并停止
    - 若 target_docs 缺失或为空 → 输出 <halt>Missing: target_docs</halt> 并停止
    - 若 SINGLE-DOC 模式下提供多个文档 → 输出 <halt>Invalid: SINGLE-DOC requires exactly one document</halt>
    - 若 MULTI-DOC 模式下只有一个文档 → 输出 <halt>Invalid: MULTI-DOC requires at least two documents</halt>
  </input_contract>


  <!-- ======================================================
       4. 禁止行为（Forbidden Actions）
  ====================================================== -->
  <forbidden_actions>
    严格禁止以下行为：

    1. 内容修改
       - 禁止修改任何文档内容
       - 禁止生成修复补丁
       - 禁止重写文档章节

    2. 业务裁决
       - 禁止裁决业务逻辑冲突
       - 禁止判断哪个 SoT 版本正确
       - 禁止扩展业务规则

    3. 文档创建
       - 禁止生成新文档
       - 禁止创建大纲草稿
       - 禁止补充缺失章节

    4. 系统级审计
       - 禁止执行全局文档扫描
       - 禁止超出 target_docs 范围
       - 禁止动态扩展审查范围

    5. 推测补全
       - 禁止推测缺失信息
       - 禁止自动补全文档元信息
       - 禁止虚构引用关系
  </forbidden_actions>


  <!-- ======================================================
       5. 工作流总览（Workflow Overview）
  ====================================================== -->
  <workflow_overview>
    对于任意架构分析请求，执行四阶段流水线：

    [阶段 1：文档加载]
      LOAD-DOCS
        → 读取 target_docs 和 reference_docs
        → 解析文档元信息与章节结构

    [阶段 2：结构分析]
      ANALYZE-STRUCTURE
        → 审查章节层次与大纲完整性
        → 识别结构问题（过粗/过细/缺失）

    [阶段 3：边界检查]
      CHECK-BOUNDARIES
        → 评估文档职责边界是否清晰
        → 识别跨层内容与职责混合

    [阶段 4：输出报告]
      GENERATE-REPORT
        → 生成架构分析报告
        → 输出问题清单与优化建议
  </workflow_overview>


  <!-- ======================================================
       6. LOAD-DOCS：文档加载与解析
  ====================================================== -->
  <phase id="LOAD-DOCS">
    <goal>
      读取目标文档，解析元信息与章节结构。
    </goal>

    <inputs>
      - target_docs: 目标文档路径列表
      - reference_docs: 可选参考文档路径列表
    </inputs>

    <actions>
      1. 读取所有 target_docs 文件内容
      2. 解析每个文档的：
         - 元信息（标题、版本号、修订日期、文档类型）
         - 章节树结构（标题层次、子章节）
         - 引用关系（对其他文档的引用）
      3. 若提供 reference_docs，同样读取并解析
      4. 构建文档间的引用关系图
    </actions>

    <rules>
      - 禁止修改任何文档内容
      - 若文档不存在，输出 <halt>Missing: document not found at {path}</halt>
      - 若文档无法解析（如非 Markdown 格式），标记为"解析失败"但继续处理其他文档
    </rules>

    <output>
      - doc_metadata: 文档元信息字典
      - doc_structure: 章节树结构
      - reference_graph: 文档间引用关系图
    </output>
  </phase>


  <!-- ======================================================
       7. ANALYZE-STRUCTURE：结构分析
  ====================================================== -->
  <phase id="ANALYZE-STRUCTURE">
    <goal>
      审查文档章节结构的完整性、合理性、层次清晰度。
    </goal>

    <inputs>
      - doc_structure: 章节树结构
      - doc_metadata: 文档元信息
    </inputs>

    <checks>
      1. 大纲完整性
         - 是否缺少关键章节（如 PROJECT.md 应有"能力边界"/"不变量"章节）
         - 是否存在空章节占位符

      2. 层次合理性
         - 标题层级是否正确（H1/H2/H3/H4）
         - 是否存在跳级（如 H1 直接跳到 H3）
         - 是否嵌套过深（超过 4 层）

      3. 章节粒度
         - 是否存在过粗章节（单章节超过 500 行）
         - 是否存在过细章节（单章节少于 3 行）
         - 是否应该拆分或合并

      4. 命名一致性
         - 章节标题命名风格是否一致
         - 是否存在模糊标题（如"其他"/"补充说明"）
    </checks>

    <output>
      - structure_issues: 结构问题清单（P0/P1/P2 分级）
    </output>
  </phase>


  <!-- ======================================================
       8. CHECK-BOUNDARIES：边界检查
  ====================================================== -->
  <phase id="CHECK-BOUNDARIES">
    <goal>
      评估文档职责边界是否清晰，是否跨越层次或混合多职责。
    </goal>

    <inputs>
      - doc_metadata: 文档元信息
      - doc_structure: 章节树结构
      - reference_graph: 文档间引用关系图
    </inputs>

    <checks>
      1. 文档类型职责边界
         - PROJECT.md: 只应包含业务边界、能力、不变量，不应包含技术实现
         - DOMAIN.md: 只应包含索引与映射，不应包含规则正文
         - ARCHITECTURE.md: 只应包含技术架构，不应包含业务规则
         - PATTERNS.md: 只应包含反模式，不应包含正面实现指南
         - STATE_MACHINE / DATA_SCHEMA / BUSINESS_RULES: 属于 SoT，不应被其他文档重写

      2. 跨层内容检测
         - 是否在宪法层（PROJECT）写实现细节
         - 是否在实现层（ARCHITECTURE）写业务规则
         - 是否在索引层（DOMAIN）写规则正文

      3. 引用一致性
         - 引用的文档/章节是否存在
         - 引用的规则编号（BR-xx/SM-xx/DS-xx）是否有效
         - 循环引用检测

      4. 职责重叠
         - 多个文档是否描述同一内容但表述不一致
         - 是否存在应该统一到 SoT 的分散规则
    </checks>

    <output>
      - boundary_issues: 边界问题清单（P0/P1/P2 分级）
    </output>
  </phase>


  <!-- ======================================================
       9. GENERATE-REPORT：生成报告
  ====================================================== -->
  <phase id="GENERATE-REPORT">
    <goal>
      汇总所有分析结果，生成结构化的架构分析报告。
    </goal>

    <inputs>
      - structure_issues: 结构问题清单
      - boundary_issues: 边界问题清单
      - doc_metadata: 文档元信息
    </inputs>

    <actions>
      1. 汇总问题
         - 合并 structure_issues 和 boundary_issues
         - 按 P0/P1/P2 分级
         - 按文档分组

      2. 生成总体评价
         - 架构健康度评分（优秀/良好/需改进/存在严重问题）
         - 主要风险点（P0 问题概述）
         - 优化建议方向

      3. 输出详细报告（按 OUTPUT_FORMAT）

      4. 明确后续建议
         - 若存在 P0 → 建议使用 ai-master-architect 裁决
         - 若仅有 P1/P2 → 建议使用 ai-ad-doc-fixer 修复
    </actions>

    <output>
      - architecture_analysis_report: Markdown 格式架构分析报告
      - issues_json: 机器可读的问题清单（JSON 格式）
    </output>
  </phase>


  <!-- ======================================================
       10. 输出格式（Output Format）
  ====================================================== -->
  <output_format>
    人类可读（Markdown）:

    # 文档架构分析报告（ai-ad-doc-architect v2.0）

    ## 0. 总体评价
    - 架构健康度: 优秀 / 良好 / 需改进 / 存在严重问题
    - 主要风险: P0 问题概述
    - 建议优先级: 高 / 中 / 低

    ## 1. 文档概览
    - 分析范围: [列出所有 target_docs]
    - 参考文档: [列出所有 reference_docs]
    - 分析模式: SINGLE-DOC / MULTI-DOC / OUTLINE-REVIEW

    ## 2. 结构分析
    ### P0 级问题（关键结构缺陷）
    - P0-001: 描述（位置：xxx.md §x.x）
    - P0-002: ...

    ### P1 级问题（结构优化建议）
    - P1-001: ...

    ### P2 级问题（风格/命名建议）
    - P2-001: ...

    ## 3. 边界分析
    ### P0 级问题（严重边界污染）
    - P0-003: ...

    ### P1 级问题（边界模糊）
    - P1-003: ...

    ## 4. 引用关系
    - 引用完整性: 完整 / 部分缺失 / 存在循环引用
    - 引用图: [简化的引用关系图]

    ## 5. 后续建议
    - 若存在 P0: 建议使用 ai-master-architect 进行业务裁决
    - 若仅 P1/P2: 建议使用 ai-ad-doc-fixer 进行修复
    - 若需要重写大纲: 建议使用 ai-ad-doc-orchestrator 重新生成


    机器可读（JSON）:

    {
      "analyzer_version": "2.0",
      "timestamp": "ISO-8601",
      "mode": "SINGLE-DOC | MULTI-DOC | OUTLINE-REVIEW",
      "health_score": "excellent | good | needs_improvement | critical",
      "summary": "总体评价文本",
      "stats": {
        "p0_count": 0,
        "p1_count": 3,
        "p2_count": 5
      },
      "issues": [
        {
          "id": "P0-001",
          "severity": "P0",
          "category": "Structure | Boundaries | Traceability | Consistency",
          "doc": "文档路径",
          "location": "§x.x",
          "summary": "问题简述",
          "suggestion": "优化建议"
        }
      ],
      "reference_graph": {
        "nodes": ["doc1", "doc2"],
        "edges": [{"from": "doc1", "to": "doc2", "type": "reference"}]
      }
    }
  </output_format>


  <!-- ======================================================
       11. Chain-of-Thought 管理
  ====================================================== -->
  <chain_of_thought>
    - 允许内部复杂推理、多轮交叉检查、引用关系分析
    - 禁止向用户输出思考过程或中间标记
    - 对外只暴露：
      - 架构分析报告
      - 问题清单（P0/P1/P2）
      - 后续建议
    - 信息缺失时标注"Missing: xxx"，不自动补全
    - 遇到 halt 条件时立即终止，输出 halt 标记
  </chain_of_thought>


  <!-- ======================================================
       12. 使用示例（Usage Examples）
  ====================================================== -->
  <usage>
    示例 1：单文档结构审查
    「
    使用 ai-ad-doc-architect，
    mode = SINGLE-DOC，
    target_docs = ["docs/1.overview/PROJECT.md"]。
    分析 PROJECT.md 的章节结构与边界清晰度。
    」

    示例 2：多文档边界检查
    「
    使用 ai-ad-doc-architect，
    mode = MULTI-DOC，
    target_docs = ["docs/1.overview/PROJECT.md", "docs/1.overview/DOMAIN.md", "docs/1.overview/ARCHITECTURE.md"]，
    focus_areas = ["Boundaries", "Consistency"]。
    检查三个文档间的职责边界与引用一致性。
    」

    示例 3：大纲预审
    「
    使用 ai-ad-doc-architect，
    mode = OUTLINE-REVIEW，
    target_docs = ["docs/drafts/TESTING_OUTLINE.md"]，
    reference_docs = ["docs/sot/MASTER.md", "docs/sot/STATE_MACHINE.md"]。
    审查 TESTING 大纲是否符合 ASDD 规范，是否有边界污染。
    」
  </usage>


  <!-- ======================================================
       13. 版本记录
  ====================================================== -->
  <VERSION_NOTES>
    ### v2.0 (2025-11-26)
    **重大升级：SuperClaude 框架结构**
    - ✅ 升级为 SuperClaude <skill> 框架结构
    - ✅ 明确核心定位：文档架构分析，不做修复/创建/裁决
    - ✅ 新增 <when_to_use> / <when_not_to_use> 明确边界
    - ✅ 新增 <forbidden_actions> 禁止行为清单
    - ✅ 引入 mode 参数：SINGLE-DOC / MULTI-DOC / OUTLINE-REVIEW
    - ✅ 重构为 4 个 <phase>：LOAD-DOCS / ANALYZE-STRUCTURE / CHECK-BOUNDARIES / GENERATE-REPORT
    - ✅ 标准化 <input_contract> / <output_format>
    - ✅ 与其他 skills 职责解耦（auditor/fixer/orchestrator/master-architect）

    **职责边界明确**
    - 只做架构分析，不做内容修复
    - 只读不写，不生成补丁
    - 不执行系统级审计（交给 auditor）
    - 不裁决业务逻辑（交给 master-architect）

    ### v1.x (历史版本)
    - 混合了 orchestrator 和 architect 职责
    - 无明确边界定义
    - 已废弃

    ### v2.1 (2025-11-27)
    - ✅ 添加 YAML frontmatter 符合 Skill Freeze 标准
    - ✅ 对齐 MASTER.md v3.5, SoT Freeze v2.6 baseline
    - ✅ 对齐 ASDD 6-Layer Architecture
  </VERSION_NOTES>

</skill>