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

审计类型

Audit	Sub-Skill	Purpose
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

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

检查内容

Check	Description
Required files	definition.md exists in each folder
Links valid	Internal links resolve
Schema valid	Follows expected structure
No orphans	All definitions referenced somewhere
No stubs	No 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

检查内容

Check	Description
Enforcement exists	.enforced_by lists actual tools
Tools configured	ESLint/hooks actually enforce
Rules followed	Codebase follows stated rules
No conflicts	Rules 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

检查每个执行机制

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

检查内容

Check	Description
File references	Documented files exist
API endpoints	Documented APIs match code
Types	Documented types match definitions
Config	Documented 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

Extract from code

从代码中提取

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

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

markdown

undefined

markdown

undefined

Audit Summary: 2026-02-06

Overview

Audit Type	Passed	Failed	Total
Tasks	15	3	18
Definitions	21	2	23
Rules	10	1	11
Drift	41	4	45
Total	87	10	97

Audit Type	Passed	Failed	Total
Tasks	15	3	18
Definitions	21	2	23
Rules	10	1	11
Drift	41	4	45
Total	87	10	97

Pass Rate

89.7%

Critical Issues

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

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

Recommendations

Install husky:
```
npm install -D husky
```
Update User type documentation
Re-implement spell_routes task

Install husky:
```
npm install -D husky
```
Update User type documentation
Re-implement spell_routes task

Next Audit

Scheduled: 2026-02-13

---

Scheduled: 2026-02-13

---

Scheduling Audits

审计计划

CI Integration

CI 集成

yaml

undefined

yaml

undefined

.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

信号文件参考

Signal	Location	Purpose
`.last_audited`	Any folder	When last audited
`.audit_passed`	Any folder	Passed last audit
`.audit_failed`	pending/	Failed audit, moved back
`.needs_review`	Any folder	Flagged for review

信号文件	位置	用途
`.last_audited`	任意文件夹	记录上次审计时间
`.audit_passed`	任意文件夹	标记上次审计通过
`.audit_failed`	pending/	标记审计失败，已回退
`.needs_review`	任意文件夹	标记需要评审