Back to Details

ogt-docs-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OGT Docs - Audit

OGT Docs - 审计

Root skill for running documentation and project audits.
用于执行文档和项目审计的根技能。

Overview

概述

Audits verify that documentation matches reality and that project standards are being followed. This skill routes to specialized audit types.
mermaid
flowchart TB
    AUDIT["ogt-docs-audit"] --> TASK["ogt-docs-audit-task"]
    AUDIT --> DEF["ogt-docs-audit-define"]
    AUDIT --> RULES["ogt-docs-audit-rules"]
    AUDIT --> CODE["ogt-docs-audit-code"]
    AUDIT --> DRIFT["ogt-docs-audit-drift"]

    TASK --> |verify| DONE["done/ tasks"]
    DEF --> |validate| DEFS["definitions"]
    RULES --> |check| ENFORCEMENT["rule enforcement"]
    CODE --> |scan| CODEBASE["codebase"]
    DRIFT --> |compare| SYNC["docs vs code"]
审计用于验证文档是否与实际情况相符，以及项目标准是否得到遵循。本技能会将请求路由至不同类型的专项审计。
mermaid
flowchart TB
    AUDIT["ogt-docs-audit"] --> TASK["ogt-docs-audit-task"]
    AUDIT --> DEF["ogt-docs-audit-define"]
    AUDIT --> RULES["ogt-docs-audit-rules"]
    AUDIT --> CODE["ogt-docs-audit-code"]
    AUDIT --> DRIFT["ogt-docs-audit-drift"]

    TASK --> |verify| DONE["done/ tasks"]
    DEF --> |validate| DEFS["definitions"]
    RULES --> |check| ENFORCEMENT["rule enforcement"]
    CODE --> |scan| CODEBASE["codebase"]
    DRIFT --> |compare| SYNC["docs vs code"]

When to Use

适用场景

  • Before releases to validate project health
  • Periodically (weekly/monthly) for maintenance
  • When onboarding to understand current state
  • After major changes to verify consistency
  • When bugs suggest documentation drift
  • 发布前验证项目健康状况
  • 定期（每周/每月）进行维护检查
  • 新成员入职时了解项目当前状态
  • 重大变更后验证一致性
  • 出现 bug 暗示文档与实际存在偏差时

Audit Types

审计类型

AuditSub-SkillPurpose
Task
ogt-docs-audit-task
Verify done/ tasks exist in code
Definition(inline)Validate definition completeness
Rules(inline)Check rule enforcement
Code(inline)Scan code for issues
Drift(inline)Compare docs to reality
审计类型子技能用途
任务审计
ogt-docs-audit-task
验证已完成任务在代码中已实现
定义审计(inline)验证定义是否完整且一致
规则审计(inline)检查规则是否得到执行
代码审计(inline)扫描代码中的问题
偏差审计(inline)对比文档与实际情况的差异

Quick Commands

快速命令

bash
undefined
bash
undefined

Full project audit

完整项目审计

ogt audit all
ogt audit all

Specific audit types

特定类型审计

ogt audit tasks # Verify done/ tasks ogt audit definitions # Check definition completeness ogt audit rules # Verify rule enforcement ogt audit drift # Find docs/code mismatches

---
ogt audit tasks # 验证已完成任务 ogt audit definitions # 检查定义完整性 ogt audit rules # 验证规则执行情况 ogt audit drift # 查找文档与代码的偏差

---

Audit: Tasks

审计：任务

Verify that completed tasks have working implementations.
Delegate to: 
ogt-docs-audit-task
bash
ogt audit tasks
See 
ogt-docs-audit-task
for complete documentation.
验证已完成的任务是否有可用的实现。
委托至： 
ogt-docs-audit-task
bash
ogt audit tasks
详细文档请参考 
ogt-docs-audit-task
。

Audit: Definitions

审计：定义

Validate that definitions are complete and consistent.
验证定义是否完整且一致。

What It Checks

检查内容

CheckDescription
Required filesdefinition.md exists in each folder
Links validInternal links resolve
Schema validFollows expected structure
No orphansAll definitions referenced somewhere
No stubsNo empty/placeholder definitions
检查项描述
必填文件存在每个文件夹中是否有 definition.md
链接有效性内部链接是否可正常访问
架构合规性是否符合预期的结构
无孤立定义所有定义均在某处被引用
无占位符定义不存在空的/占位符定义

Folder Audit

文件夹审计

bash
undefined
bash
undefined

Audit all definitions

审计所有定义

find docs/define -type d -mindepth 2 | while read dir; do if [ ! -f "$dir/definition.md" ] && [ ! -f "$dir/feature.md" ]; then echo "MISSING: $dir needs primary document" fi done
undefined
find docs/define -type d -mindepth 2 | while read dir; do if [ ! -f "$dir/definition.md" ] && [ ! -f "$dir/feature.md" ]; then echo "MISSING: $dir needs primary document" fi done
undefined

Completeness Audit

完整性审计

Check that definitions have required sections:
bash
undefined
检查定义是否包含必填章节：
bash
undefined

For each definition.md, check for required sections

检查每个 definition.md 是否包含必填章节

for file in $(find docs/define -name "definition.md"); do missing="" grep -q "## Summary" "$file" || missing+="Summary " grep -q "## Details|## The " "$file" || missing+="Details "
if [ -n "$missing" ]; then echo "INCOMPLETE: $file missing: $missing" fi done
undefined
for file in $(find docs/define -name "definition.md"); do missing="" grep -q "## Summary" "$file" || missing+="Summary " grep -q "## Details|## The " "$file" || missing+="Details "
if [ -n "$missing" ]; then echo "INCOMPLETE: $file missing: $missing" fi done
undefined

Example Output

示例输出

Auditing definitions...

docs/define/features/
  ✓ user_auth/feature.md - Complete
  ✓ search/feature.md - Complete
  ✗ notifications/ - MISSING feature.md

docs/define/code/services/
  ✓ auth_service/definition.md - Complete
  ✗ api_client/definition.md - Missing: Examples section

Summary:
  Total: 24
  Complete: 21
  Incomplete: 2
  Missing: 1
Auditing definitions...

docs/define/features/
  ✓ user_auth/feature.md - Complete
  ✓ search/feature.md - Complete
  ✗ notifications/ - MISSING feature.md

docs/define/code/services/
  ✓ auth_service/definition.md - Complete
  ✗ api_client/definition.md - Missing: Examples section

Summary:
  Total: 24
  Complete: 21
  Incomplete: 2
  Missing: 1

Audit: Rules

审计：规则

Verify that rules are enforced and up-to-date.
验证规则是否得到执行且为最新版本。

What It Checks

检查内容

CheckDescription
Enforcement exists.enforced_by lists actual tools
Tools configuredESLint/hooks actually enforce
Rules followedCodebase follows stated rules
No conflictsRules don't contradict each other
检查项描述
执行机制存在.enforced_by 中列出的工具实际存在
工具已配置ESLint/钩子已正确配置并执行规则
规则被遵循代码库符合已声明的规则
无规则冲突规则之间不存在矛盾

Enforcement Audit

执行机制审计

bash
undefined
bash
undefined

For each rule, verify enforcement mechanism exists

检查每个规则是否有对应的执行机制

for rule_dir in $(find docs/rules -type d -mindepth 2); do enforced_by="$rule_dir/.enforced_by"
if [ ! -f "$enforced_by" ]; then echo "MISSING: $rule_dir has no .enforced_by" continue fi

Check each enforcement mechanism

while read mechanism; do case "$mechanism" in eslint*) grep -q "eslint" package.json || echo " NOT CONFIGURED: eslint" ;; commitlint*) grep -q "commitlint" package.json || echo " NOT CONFIGURED: commitlint" ;; husky*) test -d .husky || echo " NOT CONFIGURED: husky" ;; esac done < "$enforced_by" done
undefined
for rule_dir in $(find docs/rules -type d -mindepth 2); do enforced_by="$rule_dir/.enforced_by"
if [ ! -f "$enforced_by" ]; then echo "MISSING: $rule_dir has no .enforced_by" continue fi

检查每个执行机制

while read mechanism; do case "$mechanism" in eslint*) grep -q "eslint" package.json || echo " NOT CONFIGURED: eslint" ;; commitlint*) grep -q "commitlint" package.json || echo " NOT CONFIGURED: commitlint" ;; husky*) test -d .husky || echo " NOT CONFIGURED: husky" ;; esac done < "$enforced_by" done
undefined

Compliance Audit

合规性审计

Check if codebase follows rules:
bash
undefined
检查代码库是否遵循规则：
bash
undefined

Example: Check naming convention compliance

示例：检查命名规范合规性

Rule: React components must be PascalCase

规则：React 组件必须使用 PascalCase 命名

find src -name "*.tsx" -type f | while read file; do basename=$(basename "$file" .tsx) if [[ ! "$basename" =~ ^[A-Z] ]]; then echo "VIOLATION: $file - Component not PascalCase" fi done
undefined
find src -name "*.tsx" -type f | while read file; do basename=$(basename "$file" .tsx) if [[ ! "$basename" =~ ^[A-Z] ]]; then echo "VIOLATION: $file - Component not PascalCase" fi done
undefined

Example Output

示例输出

Auditing rules...

docs/rules/code/typescript/
  ✓ strict_mode - Enforced by: tsc
  ✓ no_any - Enforced by: eslint

docs/rules/git/commits/
  ✓ conventional - Enforced by: commitlint
  ✗ conventional - NOT ENFORCED: husky not installed

docs/rules/code/naming/files/
  ✗ kebab_case - 3 violations found

Summary:
  Rules: 12
  Enforced: 10
  Unenforced: 1
  Violations: 3
Auditing rules...

docs/rules/code/typescript/
  ✓ strict_mode - Enforced by: tsc
  ✓ no_any - Enforced by: eslint

docs/rules/git/commits/
  ✓ conventional - Enforced by: commitlint
  ✗ conventional - NOT ENFORCED: husky not installed

docs/rules/code/naming/files/
  ✗ kebab_case - 3 violations found

Summary:
  Rules: 12
  Enforced: 10
  Unenforced: 1
  Violations: 3

Audit: Drift

审计：偏差

Find mismatches between documentation and code.
查找文档与代码之间的不匹配。

What It Checks

检查内容

CheckDescription
File referencesDocumented files exist
API endpointsDocumented APIs match code
TypesDocumented types match definitions
ConfigDocumented config matches actual
检查项描述
文件引用有效性文档中引用的文件是否存在
API 端点一致性文档中记录的 API 与代码是否匹配
类型定义一致性文档中记录的类型与代码定义是否匹配
配置一致性文档中记录的配置与实际配置是否匹配

File Reference Audit

文件引用审计

bash
undefined
bash
undefined

Find file paths in docs and verify they exist

查找文档中引用的文件路径并验证其是否存在

grep -roh "src/[^[:space:]"'`]*.(ts|tsx|js)" docs/ | sort -u | while read path; do if [ ! -f "$path" ]; then echo "DRIFT: $path referenced in docs but doesn't exist" fi done
undefined
grep -roh "src/[^[:space:]"'`]*.(ts|tsx|js)" docs/ | sort -u | while read path; do if [ ! -f "$path" ]; then echo "DRIFT: $path referenced in docs but doesn't exist" fi done
undefined

API Drift Audit

API 偏差审计

bash
undefined
bash
undefined

Compare documented endpoints to actual routes

对比文档中记录的端点与实际路由

Extract from docs

从文档中提取

grep -roh "POST|GET|PUT|DELETE /api/[^[:space:]]*" docs/ | sort -u > /tmp/doc-endpoints
grep -roh "POST|GET|PUT|DELETE /api/[^[:space:]]*" docs/ | sort -u > /tmp/doc-endpoints

Extract from code

从代码中提取

grep -roh "router.(post|get|put|delete)(['"][^'"]*" src/routes/ | sort -u > /tmp/code-endpoints
grep -roh "router.(post|get|put|delete)(['"][^'"]*" src/routes/ | sort -u > /tmp/code-endpoints

Compare

对比差异

diff /tmp/doc-endpoints /tmp/code-endpoints
undefined
diff /tmp/doc-endpoints /tmp/code-endpoints
undefined

Example Output

示例输出

Auditing for drift...

File References:
  ✗ docs/define/code/services/auth.md references:
    - src/services/AuthService.ts (EXISTS)
    - src/services/TokenManager.ts (MISSING - was renamed to TokenService.ts)

API Endpoints:
  ✗ docs/define/code/api/users.md documents:
    - POST /api/users (EXISTS)
    - GET /api/users/:id (EXISTS)
    - DELETE /api/users/:id (MISSING - not implemented)

Type Definitions:
  ✗ docs/define/code/data_models/user.md shows:
    - User.email: string (MATCHES)
    - User.role: 'admin' | 'user' (DRIFT - code has 'admin' | 'user' | 'guest')

Summary:
  Checked: 45 references
  Valid: 41
  Drift: 4
Auditing for drift...

File References:
  ✗ docs/define/code/services/auth.md references:
    - src/services/AuthService.ts (EXISTS)
    - src/services/TokenManager.ts (MISSING - was renamed to TokenService.ts)

API Endpoints:
  ✗ docs/define/code/api/users.md documents:
    - POST /api/users (EXISTS)
    - GET /api/users/:id (EXISTS)
    - DELETE /api/users/:id (MISSING - not implemented)

Type Definitions:
  ✗ docs/define/code/data_models/user.md shows:
    - User.email: string (MATCHES)
    - User.role: 'admin' | 'user' (DRIFT - code has 'admin' | 'user' | 'guest')

Summary:
  Checked: 45 references
  Valid: 41
  Drift: 4

Full Project Audit

完整项目审计

Run all audits at once:
bash
#!/bin/bash
一次性运行所有审计：
bash
#!/bin/bash

audit-all.sh

audit-all.sh

echo "=== OGT Full Project Audit ===" echo "Date: $(date)" echo ""
echo "## Task Audit" ogt audit tasks echo ""
echo "## Definition Audit" ./scripts/audit-definitions.sh echo ""
echo "## Rules Audit" ./scripts/audit-rules.sh echo ""
echo "## Drift Audit" ./scripts/audit-drift.sh echo ""
echo "=== Audit Complete ==="

---
echo "=== OGT Full Project Audit ===" echo "Date: $(date)" echo ""
echo "## Task Audit" ogt audit tasks echo ""
echo "## Definition Audit" ./scripts/audit-definitions.sh echo ""
echo "## Rules Audit" ./scripts/audit-rules.sh echo ""
echo "## Drift Audit" ./scripts/audit-drift.sh echo ""
echo "=== Audit Complete ==="

---

Audit Report Format

审计报告格式

docs/todo/audit_log/{date}/summary.md

docs/todo/audit_log/{date}/summary.md

markdown
undefined
markdown
undefined

Audit Summary: 2026-02-06

Audit Summary: 2026-02-06

Overview

Overview

Audit TypePassedFailedTotal
Tasks15318
Definitions21223
Rules10111
Drift41445
Total871097
Audit TypePassedFailedTotal
Tasks15318
Definitions21223
Rules10111
Drift41445
Total871097

Pass Rate

Pass Rate

89.7%
89.7%

Critical Issues

Critical Issues

  1. Task: spell_routes - Never implemented (moved to pending/)
  2. Rule: commit format - Husky not installed
  3. Drift: User.role - Type mismatch between docs and code
  1. Task: spell_routes - Never implemented (moved to pending/)
  2. Rule: commit format - Husky not installed
  3. Drift: User.role - Type mismatch between docs and code

Recommendations

Recommendations

  1. Install husky: 
    npm install -D husky
  2. Update User type documentation
  3. Re-implement spell_routes task
  1. Install husky: 
    npm install -D husky
  2. Update User type documentation
  3. Re-implement spell_routes task

Next Audit

Next Audit

Scheduled: 2026-02-13

---
Scheduled: 2026-02-13

---

Scheduling Audits

审计计划

CI Integration

CI 集成

yaml
undefined
yaml
undefined

.github/workflows/audit.yml

.github/workflows/audit.yml

name: Weekly Audit
on: schedule: - cron: "0 9 * * 1" # Monday 9am workflow_dispatch:
jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
  - name: Run audits
    run: ./scripts/audit-all.sh > audit-report.md

  - name: Check for failures
    run: |
      if grep -q "FAIL\|MISSING\|DRIFT" audit-report.md; then
        echo "Audit found issues"
        cat audit-report.md
        exit 1
      fi

  - name: Upload report
    uses: actions/upload-artifact@v4
    with:
      name: audit-report
      path: audit-report.md
undefined
name: Weekly Audit
on: schedule: - cron: "0 9 * * 1" # Monday 9am workflow_dispatch:
jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
  - name: Run audits
    run: ./scripts/audit-all.sh > audit-report.md

  - name: Check for failures
    run: |
      if grep -q "FAIL\|MISSING\|DRIFT" audit-report.md; then
        echo "Audit found issues"
        cat audit-report.md
        exit 1
      fi

  - name: Upload report
    uses: actions/upload-artifact@v4
    with:
      name: audit-report
      path: audit-report.md
undefined

Local Cron

本地定时任务

bash
undefined
bash
undefined

Add to crontab

添加至 crontab

0 9 * * 1 cd /path/to/project && ./scripts/audit-all.sh >> logs/audit.log 2>&1

---
0 9 * * 1 cd /path/to/project && ./scripts/audit-all.sh >> logs/audit.log 2>&1

---

Signal Files Reference

信号文件参考

SignalLocationPurpose
.last_audited
Any folderWhen last audited
.audit_passed
Any folderPassed last audit
.audit_failed
pending/Failed audit, moved back
.needs_review
Any folderFlagged for review
信号文件位置用途
.last_audited
任意文件夹记录上次审计时间
.audit_passed
任意文件夹标记上次审计通过
.audit_failed
pending/标记审计失败，已回退
.needs_review
任意文件夹标记需要评审

Audit Checklist

审计检查清单

Before considering an audit complete:
  • All task audits run
  • All definition folders checked
  • All rules enforcement verified
  • Drift check completed
  • Failed items moved/documented
  • Audit log created
  • Summary generated
  • Critical issues flagged
  • Next audit scheduled
审计完成前需确认：
  • 所有任务审计已运行
  • 所有定义文件夹已检查
  • 所有规则执行情况已验证
  • 偏差检查已完成
  • 未通过项已被移动/记录
  • 已创建审计日志
  • 已生成审计摘要
  • 重大问题已标记
  • 已计划下次审计