Back to Details

documentation-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Audit

文档审计

Overview

概述

Comprehensive documentation sync when drift is detected. Analyzes codebase and creates or updates all documentation artifacts to achieve full synchronization.
Core principle: Documentation must reflect reality. This skill brings them into alignment.
Announce at start: "I'm using documentation-audit to synchronize all documentation with the current codebase."
当检测到文档漂移时，进行全面的文档同步。分析代码库并创建或更新所有文档工件，以实现完全同步。
核心原则： 文档必须反映实际情况。本技能可使二者保持一致。
开始时需告知： "我正在使用documentation-audit技能，将所有文档与当前代码库同步。"

When This Skill Triggers

技能触发场景

This skill is invoked when:
TriggerSource
API documentation drift
api-documentation
skill
Features documentation drift
features-documentation
skill
Missing documentation filesAny documentation check
Manual requestUser or orchestrator
本技能在以下场景被调用：
触发条件来源
API文档漂移
api-documentation
技能
功能文档漂移
features-documentation
技能
缺失文档文件任何文档检查
手动请求用户或编排器

The Audit Process

审计流程

Phase 1: Discovery

阶段1：发现

bash
echo "=== Documentation Audit: Discovery Phase ==="
bash
echo "=== Documentation Audit: Discovery Phase ==="

Find all documentation files

Find all documentation files

DOC_FILES=$(find . -name ".md" -o -name ".yaml" -o -name "*.json" |
grep -E "(doc|api|swagger|openapi|feature|guide|readme)" |
grep -v node_modules | grep -v .git)
echo "Found documentation files:" echo "$DOC_FILES"
DOC_FILES=$(find . -name ".md" -o -name ".yaml" -o -name "*.json" |
grep -E "(doc|api|swagger|openapi|feature|guide|readme)" |
grep -v node_modules | grep -v .git)
echo "Found documentation files:" echo "$DOC_FILES"

Find API documentation

Find API documentation

API_DOC=$(find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "openapi.json" | head -1) echo "API Documentation: ${API_DOC:-MISSING}"
API_DOC=$(find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "openapi.json" | head -1) echo "API Documentation: ${API_DOC:-MISSING}"

Find features documentation

Find features documentation

FEATURE_DOC=$(find . -name "features.md" -o -name "FEATURES.md" | head -1) echo "Features Documentation: ${FEATURE_DOC:-MISSING}"
undefined
FEATURE_DOC=$(find . -name "features.md" -o -name "FEATURES.md" | head -1) echo "Features Documentation: ${FEATURE_DOC:-MISSING}"
undefined

Phase 2: API Audit

阶段2：API审计

If API endpoints exist:
bash
echo "=== Documentation Audit: API Phase ==="
若存在API端点：
bash
echo "=== Documentation Audit: API Phase ==="

Detect API framework

Detect API framework

detect_api_framework() { if grep -r "express" package.json 2>/dev/null; then echo "express"; return; fi if grep -r "fastify" package.json 2>/dev/null; then echo "fastify"; return; fi if grep -r "@nestjs" package.json 2>/dev/null; then echo "nestjs"; return; fi if grep -r "fastapi" requirements.txt 2>/dev/null; then echo "fastapi"; return; fi if grep -r "flask" requirements.txt 2>/dev/null; then echo "flask"; return; fi if [ -f "go.mod" ]; then echo "go"; return; fi echo "unknown" }
FRAMEWORK=$(detect_api_framework) echo "Detected framework: $FRAMEWORK"
detect_api_framework() { if grep -r "express" package.json 2>/dev/null; then echo "express"; return; fi if grep -r "fastify" package.json 2>/dev/null; then echo "fastify"; return; fi if grep -r "@nestjs" package.json 2>/dev/null; then echo "nestjs"; return; fi if grep -r "fastapi" requirements.txt 2>/dev/null; then echo "fastapi"; return; fi if grep -r "flask" requirements.txt 2>/dev/null; then echo "flask"; return; fi if [ -f "go.mod" ]; then echo "go"; return; fi echo "unknown" }
FRAMEWORK=$(detect_api_framework) echo "Detected framework: $FRAMEWORK"

Extract all endpoints from code

Extract all endpoints from code

extract_endpoints() { case "$FRAMEWORK" in express|fastify) grep -rh "app.(get|post|put|delete|patch)" --include=".ts" --include=".js" |
sed "s/.app.([a-z])('([^'])'./\1 \2/" ;; nestjs) grep -rh "@(Get|Post|Put|Delete|Patch)" --include=".ts" |
sed "s/.@([A-Za-z])('([^'])'./\1 \2/" ;; fastapi) grep -rh "@app.(get|post|put|delete|patch)" --include=".py" |
sed "s/.@app.([a-z])("([^"])"./\1 \2/" ;; *) echo "Unknown framework - manual inspection required" ;; esac }
ENDPOINTS=$(extract_endpoints) echo "Found endpoints:" echo "$ENDPOINTS"
undefined
extract_endpoints() { case "$FRAMEWORK" in express|fastify) grep -rh "app.(get|post|put|delete|patch)" --include=".ts" --include=".js" |
sed "s/.app.([a-z])('([^'])'./\1 \2/" ;; nestjs) grep -rh "@(Get|Post|Put|Delete|Patch)" --include=".ts" |
sed "s/.@([A-Za-z])('([^'])'./\1 \2/" ;; fastapi) grep -rh "@app.(get|post|put|delete|patch)" --include=".py" |
sed "s/.@app.([a-z])("([^"])"./\1 \2/" ;; *) echo "Unknown framework - manual inspection required" ;; esac }
ENDPOINTS=$(extract_endpoints) echo "Found endpoints:" echo "$ENDPOINTS"
undefined

Phase 3: Features Audit

阶段3：功能审计

bash
echo "=== Documentation Audit: Features Phase ==="
bash
echo "=== Documentation Audit: Features Phase ==="

Find user-facing components

Find user-facing components

find_features() {

React components in pages/views

find . -path "/pages/" -name ".tsx" -o -path "/views/" -name ".tsx" |
xargs -I {} basename {} .tsx 2>/dev/null

Feature flags

grep -rh "featureFlag|feature:" --include=".ts" --include=".tsx" |
sed "s/.['"]feature[':]\s['"]?([^'"])['"]?./\1/" 2>/dev/null

Config options exposed to users

grep -rh "config.|settings." --include=".ts" |
grep -v "import|require" |
sed "s/.(config|settings).([a-zA-Z])./\2/" 2>/dev/null | sort -u }
FEATURES=$(find_features) echo "Discovered features:" echo "$FEATURES"
undefined
find_features() {

React components in pages/views

find . -path "/pages/" -name ".tsx" -o -path "/views/" -name ".tsx" |
xargs -I {} basename {} .tsx 2>/dev/null

Feature flags

grep -rh "featureFlag|feature:" --include=".ts" --include=".tsx" |
sed "s/.['"]feature[':]\s['"]?([^'"])['"]?./\1/" 2>/dev/null

Config options exposed to users

grep -rh "config.|settings." --include=".ts" |
grep -v "import|require" |
sed "s/.(config|settings).([a-zA-Z])./\2/" 2>/dev/null | sort -u }
FEATURES=$(find_features) echo "Discovered features:" echo "$FEATURES"
undefined

Phase 4: Generate Missing Documentation

阶段4：生成缺失的文档

Create OpenAPI if Missing

若缺失则创建OpenAPI文件

yaml
undefined
yaml
undefined

Template for new OpenAPI file

Template for new OpenAPI file

openapi: 3.0.3 info: title: [PROJECT_NAME] API description: | API documentation for [PROJECT_NAME]. Generated by documentation-audit skill. version: 1.0.0 contact: name: API Support servers:

Endpoints will be added here

components: schemas: Error: type: object properties: code: type: string message: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT
undefined
openapi: 3.0.3 info: title: [PROJECT_NAME] API description: | API documentation for [PROJECT_NAME]. Generated by documentation-audit skill. version: 1.0.0 contact: name: API Support servers:

Endpoints will be added here

components: schemas: Error: type: object properties: code: type: string message: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT
undefined

Create Features Doc if Missing

若缺失则创建功能文档

markdown
undefined
markdown
undefined

Features

Features

Generated by documentation-audit skill. Update with accurate descriptions.
Generated by documentation-audit skill. Update with accurate descriptions.

Overview

Overview

[Brief description of the product]
[Brief description of the product]

Core Features

Core Features

[Feature 1]

[Feature 1]

Description: [What it does]
How to Use:
  1. [Step 1]
  2. [Step 2]
Description: [What it does]
How to Use:
  1. [Step 1]
  2. [Step 2]

Additional Features

Additional Features

[List additional features discovered]
Last updated: [DATE] Note: This file was auto-generated. Review and enhance descriptions.
undefined
[List additional features discovered]
Last updated: [DATE] Note: This file was auto-generated. Review and enhance descriptions.
undefined

Phase 5: Update Existing Documentation

阶段5：更新现有文档

For each discovered but undocumented item:
  1. API Endpoints - Add to OpenAPI spec with:
    • Path and method
    • Parameters (from function signature)
    • Request body schema (from DTO/type)
    • Response schema (from return type)
    • Basic description
  2. Features - Add to features doc with:
    • Feature name
    • Basic description
    • Placeholder for how-to-use
    • Note to review and enhance
对于每个已发现但未记录的项：
  1. API端点 - 添加到OpenAPI规范中，包含：
    • 路径和方法
    • 参数（来自函数签名）
    • 请求体 schema（来自DTO/类型）
    • 响应 schema（来自返回类型）
    • 基本描述
  2. 功能 - 添加到功能文档中，包含：
    • 功能名称
    • 基本描述
    • 使用方法占位符
    • 需人工审核的说明

Phase 6: Validation

阶段6：验证

bash
echo "=== Documentation Audit: Validation Phase ==="
bash
echo "=== Documentation Audit: Validation Phase ==="

Validate OpenAPI

Validate OpenAPI

if [ -f "openapi.yaml" ]; then yq '.' openapi.yaml > /dev/null 2>&1 && echo "OpenAPI: Valid YAML" || echo "OpenAPI: Invalid YAML" fi
if [ -f "openapi.yaml" ]; then yq '.' openapi.yaml > /dev/null 2>&1 && echo "OpenAPI: Valid YAML" || echo "OpenAPI: Invalid YAML" fi

Validate Markdown

Validate Markdown

for file in docs/*.md; do if [ -f "$file" ]; then # Check for required sections if ! grep -q "^## " "$file"; then echo "WARNING: $file missing section headers" fi fi done
for file in docs/*.md; do if [ -f "$file" ]; then # Check for required sections if ! grep -q "^## " "$file"; then echo "WARNING: $file missing section headers" fi fi done

Check completeness

Check completeness

ENDPOINTS_DOCUMENTED=$(yq '.paths | keys | length' openapi.yaml 2>/dev/null || echo 0) ENDPOINTS_IN_CODE=$(extract_endpoints | wc -l)
echo "Endpoints in code: $ENDPOINTS_IN_CODE" echo "Endpoints documented: $ENDPOINTS_DOCUMENTED"
if [ "$ENDPOINTS_DOCUMENTED" -lt "$ENDPOINTS_IN_CODE" ]; then echo "WARNING: Some endpoints still undocumented" fi
undefined
ENDPOINTS_DOCUMENTED=$(yq '.paths | keys | length' openapi.yaml 2>/dev/null || echo 0) ENDPOINTS_IN_CODE=$(extract_endpoints | wc -l)
echo "Endpoints in code: $ENDPOINTS_IN_CODE" echo "Endpoints documented: $ENDPOINTS_DOCUMENTED"
if [ "$ENDPOINTS_DOCUMENTED" -lt "$ENDPOINTS_IN_CODE" ]; then echo "WARNING: Some endpoints still undocumented" fi
undefined

Audit Report

审计报告

Post audit results to GitHub issue:
markdown
undefined
将审计结果发布到GitHub Issue：
markdown
undefined

Documentation Audit Complete

Documentation Audit Complete

Audit Date: [ISO_TIMESTAMP] Triggered By: [api-documentation|features-documentation|manual]
Audit Date: [ISO_TIMESTAMP] Triggered By: [api-documentation|features-documentation|manual]

Summary

Summary

CategoryBeforeAfterStatus
API Endpoints[N] undocumented[N] documented[COMPLETE/PARTIAL]
Features[N] undocumented[N] documented[COMPLETE/PARTIAL]
General Docs[N] missing[N] created[COMPLETE/PARTIAL]
CategoryBeforeAfterStatus
API Endpoints[N] undocumented[N] documented[COMPLETE/PARTIAL]
Features[N] undocumented[N] documented[COMPLETE/PARTIAL]
General Docs[N] missing[N] created[COMPLETE/PARTIAL]

Files Created

Files Created

  • openapi.yaml
    - API documentation
  • docs/features.md
    - Features documentation
  • openapi.yaml
    - API documentation
  • docs/features.md
    - Features documentation

Files Updated

Files Updated

  • openapi.yaml
    - Added [N] endpoints
  • docs/features.md
    - Added [N] features
  • openapi.yaml
    - Added [N] endpoints
  • docs/features.md
    - Added [N] features

Requires Manual Review

Requires Manual Review

  • Verify API response schemas
  • Enhance feature descriptions
  • Add usage examples
  • Review security documentation
  • Verify API response schemas
  • Enhance feature descriptions
  • Add usage examples
  • Review security documentation

Next Steps

Next Steps

  1. Review generated documentation
  2. Add detailed descriptions
  3. Include examples
  4. Validate with stakeholders
documentation-audit skill completed
undefined
  1. Review generated documentation
  2. Add detailed descriptions
  3. Include examples
  4. Validate with stakeholders
documentation-audit skill completed
undefined

Checklist

检查清单

During audit:
  • All documentation files discovered
  • API framework detected
  • All endpoints extracted from code
  • All features extracted from code
  • Missing documentation files created
  • Existing documentation updated
  • All files validated
  • Audit report posted to issue
  • Changes committed
审计期间需完成：
  • 发现所有文档文件
  • 检测到API框架
  • 从代码中提取所有端点
  • 从代码中提取所有功能
  • 创建缺失的文档文件
  • 更新现有文档
  • 验证所有文件
  • 将审计报告发布到Issue
  • 提交更改

Quality Standards

质量标准

Generated documentation must meet:
StandardRequirement
CompletenessEvery endpoint/feature listed
ValidityYAML/JSON validates
StructureRequired sections present
PlaceholdersClear markers for manual review
AttributionGenerated by skill noted
生成的文档必须满足：
标准要求
完整性列出每个端点/功能
有效性YAML/JSON可通过验证
结构性包含必要的章节
占位符清晰标记需人工审核的内容
归属标注由技能生成

Integration

集成

This skill is invoked by:
SkillWhen
api-documentation
API drift detected
features-documentation
Features drift detected
issue-driven-development
Documentation step
This skill uses:
ToolPurpose
Glob/Grep
Discover code artifacts
Read
Analyze existing docs
Write
Create new docs
Edit
Update existing docs
yq
Validate YAML
jq
Validate JSON
本技能由以下技能调用：
技能调用时机
api-documentation
检测到API漂移时
features-documentation
检测到功能漂移时
issue-driven-development
文档步骤中
本技能使用以下工具：
工具用途
Glob/Grep
发现代码工件
Read
分析现有文档
Write
创建新文档
Edit
更新现有文档
yq
验证YAML
jq
验证JSON