documentation-specialist

Documentation Specialist 是一个面向软件文档工作的技能，覆盖文档创建、代码反向提取、审计、格式转换和图表绘制。

用途 该技能用于生成专业软件文档，包括 SRS、PRD、OpenAPI、SDD、架构文档、用户手册、教程和 Runbook。它支持从零创建文档、从代码反向生成文档、审查和改进现有文档、转换文档格式以及绘制图表。

主要能力

• 从模板创建文档：SRS、PRD、SDD（arc42）、架构文档（C4 简版）、OpenAPI、用户手册、How-To 指南、入门指南、开发者教程、Runbook。
• 从代码反向生成文档：支持 Spring Boot 和 FastAPI 框架，通过检测文件（如 pom.xml、@SpringBootApplication、requirements.txt、from fastapi import）识别框架并加载对应映射。
• 审计现有文档：审查并改进已有文档。
• 格式转换：支持 MD 到 DOCX 到 PDF 的转换。
• 图表绘制：优先使用 Mermaid（C4、序列图、类图、ER 图、状态图、流程图），UI 线框图使用 PlantUML Salt，其余 UML 类型（用例图、时序图、ArchiMate、nwdiag、WBS）使用 PlantUML。

使用方式 技能执行流程为：分类意图、选择一种写作风格包、加载对应工作流、执行步骤、生成文档、提供后处理选项。

写作风格包（必须选择一种，不可混用）：

• STE100（默认）：适用于流程、Runbook、手册、架构文档、代码走查、需求，以及未指定 Google 风格的请求。来源为 ste100 技能。
• google-docs-style：当用户明确说“Google style”“Google docs style”或“developer style guide”时使用。来源为 google-docs-style 技能。 默认使用 STE100。仅当用户指定 Google 风格时切换。若两者都被提及，需询问使用哪一种，不可同时应用。

硬性禁令（两种风格包均适用）：

• 不使用长破折号（—）或双连字符（--）作为标点，应使用句号或逗号。
• 不以 So、That、Thus 或 Hence 开头。
• 不以悬垂指示词开头（如“That is why...”作为引导）。 STE100 额外要求：短句、每步一条指令、主动语态、不使用缩写、不使用 e.g. / i.e. / etc.、步骤中不使用弱情态动词。

意图分类与工作流：

• CREATE_NEW：关键词“create”“generate”“write”加文档类型，使用 greenfield-workflow.md。
• DESIGN：关键词“DESIGN_DOC.md”“SDD”“software design document”“arc42”“architecture document”“architecture.md”，使用 design-workflow.md。SDD 保存为 DESIGN_DOC.md 或 docs/DESIGN_DOC.md，C4 简版保存为 docs/architecture.md。
• CODE_TO_DOCS：关键词“document”“extract”或路径引用，使用 brownfield-workflow.md。
• AUDIT：关键词“audit”“review”“check”“improve”，使用 audit-workflow.md。
• CONVERT：关键词“convert”“to Word”“to PDF”，使用 convert-workflow.md。
• DIAGRAM：关键词“diagram”“C4”“sequence”“ER”“class”“state”“wireframe”“mock”“Salt”，使用 diagram-workflow.md。
• USER_DOCS：关键词“user manual”“how-to”“getting started”，使用 user-docs-workflow.md。
• TUTORIAL：关键词“tutorial”“API guide”“CLI docs”，使用 tutorial-workflow.md。
• RUNBOOK：关键词“runbook”“procedure”“incident”，使用 runbook-workflow.md。 注意：仅加载当前意图所需的工作流，避免加载多个。

文档类型与模板对应：

• SRS：requirements-srs.md，默认输出 docs/srs.md。
• PRD：requirements-prd.md，默认输出 docs/prd.md。
• SDD（arc42）：DESIGN_DOC.md，默认输出 DESIGN_DOC.md。
• 架构（C4 简版）：architecture.md，默认输出 docs/architecture.md。
• OpenAPI：api-openapi.yaml，默认输出 openapi.yaml。
• 用户手册：user-manual.md。
• How-To 指南：howto-guide.md。
• 入门指南：getting-started.md。
• 开发者教程：developer-tutorial.md。
• Runbook：runbook.md。

框架检测（反向生成）：

• Spring Boot：检测 pom.xml、@SpringBootApplication，映射文件 spring-boot-mapping.yaml。
• FastAPI：检测 requirements.txt、from fastapi import，映射文件 fastapi-mapping.yaml。 流程：Glob 检测文件，Grep 模式，加载映射，遵循 brownfield 工作流。

按需资源：仅加载当前任务所需内容。工作流包括 design-workflow.md、greenfield-workflow.md、brownfield-workflow.md、audit-workflow.md、convert-workflow.md、diagram-workflow.md、user-docs-workflow.md、tutorial-workflow.md、runbook-workflow.md。参考指南包括 comprehensive-guide.md（导航到全部 27 个参考指南）、11-voice-and-style.md（STE100 与 Google 风格对比及硬性禁令）、04-diagrams-selection.md（Mermaid 优先、PlantUML 剩余类型、Salt UI 线框图）、03-design-arc42.md（arc42 十二个章节）。示例包括 DESIGN 示例（ecommerce-sdd.md、architecture-doc.md、ui-wireframes.md）、Brownfield SDD 示例（spring-boot-sdd.md）以及该技能自身的 SDD（DESIGN_DOC.md）。

技能集成：

• ste100：默认风格包，用于流程、Runbook、架构文档、走查、需求。
• google-docs-style：用户指定 Google 风格时使用，与 ste100 互斥。
• design-doc-mermaid：默认图表，包括 C4、流程图、序列图、类图、ER 图、状态图、组件视图。GitHub wiki 可渲染该围栏。
• plantuml：UI 线框图（Salt）、用例图、时序图、ArchiMate、nwdiag、WBS。始终输出 PNG 或 SVG。
• docx：请求包含 Word 格式时使用。
• pdf：请求包含 PDF 格式时使用。 当 WikiTicket SDD 要求架构文档、代码走查或需求文档时，使用此技能处理文字和线框图，使用 design-doc-mermaid 处理所有 GitHub 安全图表，仅对剩余类型使用 plantuml。GitHub wiki 中嵌入 Mermaid，PlantUML 图片随页面上传。Confluence 中将 Mermaid 和 PlantUML 渲染为 PNG 或 SVG 并上传两者。

错误处理：

• 无法检测框架：询问“Is this Spring Boot, FastAPI, or another framework?”
• 缺少模板：使用最接近的匹配并告知用户。
• 技能不可用：提供仅 Markdown 的替代方案。
• 请求模糊：询问“Would you prefer SRS (formal), PRD (agile), or DESIGN_DOC.md (arc42)?”
• 同时指定两种风格包：询问使用哪一种，不可混用。
• 用户界面无 Salt：每个屏幕添加一个 PlantUML Salt 线框图，不要用 Mermaid 流程图替代。

适用场景 适用于需要创建、提取、审计、转换或绘制软件文档的开发团队、技术写作者和运维人员。特别适合需要标准化文档（如 SRS、PRD、SDD、Runbook）的项目，以及需要从 Spring Boot 或 FastAPI 代码反向生成文档的场景。

限制 该技能要求为每份文档选择一种写作风格包，不可混用。STE100 和 Google 风格有严格的写作禁令。图表绘制有明确的工具选择规则：Mermaid 优先，PlantUML 用于剩余类型，UI 线框图必须使用 PlantUML Salt。技能执行时仅加载当前意图所需的工作流，避免加载多个。部分功能依赖外部技能（如 ste100、google-docs-style、design-doc-mermaid、plantuml、docx、pdf）的可用性。