OGT Docs - Audit Task
OGT 文档 - 任务审计
Verify that completed tasks actually have working implementations in the codebase.
验证已标记为完成的任务是否在代码库中存在可正常运行的实现。
Tasks in
claim to be complete. This skill verifies those claims by checking that the implementation actually exists and works. Unverified tasks are moved back to
for re-implementation.
mermaid
flowchart LR
subgraph audit ["Audit Process"]
direction TB
A[Read task.md] --> B[Extract Acceptance Criteria]
B --> C[Verify Each Criterion]
C --> D{All Pass?}
D -->|Yes| E[Mark Verified]
D -->|No| F[Move to pending/]
end
DONE["done/task/"] --> audit
audit --> VERIFIED["done/task/ + .verified"]
audit --> PENDING["pending/task/"]
style DONE fill:#d1fae5
style VERIFIED fill:#a7f3d0
style PENDING fill:#fef3c7
目录下的任务被标记为已完成。本技能通过检查功能实现是否真实存在且可正常运行,来验证这些完成声明。未通过验证的任务将被移回
目录,等待重新实现。
mermaid
flowchart LR
subgraph audit ["Audit Process"]
direction TB
A[Read task.md] --> B[Extract Acceptance Criteria]
B --> C[Verify Each Criterion]
C --> D{All Pass?}
D -->|Yes| E[Mark Verified]
D -->|No| F[Move to pending/]
end
DONE["done/task/"] --> audit
audit --> VERIFIED["done/task/ + .verified"]
audit --> PENDING["pending/task/"]
style DONE fill:#d1fae5
style VERIFIED fill:#a7f3d0
style PENDING fill:#fef3c7
- Before a release to ensure all "done" tasks are actually done
- During periodic audits (weekly/monthly)
- When a bug reveals a task may not be complete
- When onboarding to verify codebase state
- After agent work sessions to validate claims
- 发布前:确保所有标记为“已完成”的任务确实已完成
- 定期审计:每周/每月进行一次
- 发现Bug时:验证相关任务是否未真正完成
- 新成员入职时:确认代码库的实际状态
- Agent工作会话后:验证其完成任务的声明
Different acceptance criteria require different verification methods:
| Criterion Type | Verification Method | Example |
|---|
| File exists | | "Create UserService.ts" |
| File exported | | "Export from index.ts" |
| Route exists | | "Add /users route" |
| Type exists | | "Add User type" |
| Function exists | | "Add calculateTotal()" |
| Dependency installed | | "Install lodash" |
| Pattern removed | = 0 | "Remove all console.log" |
| TypeScript compiles | | "No type errors" |
| Tests pass | | "Tests pass" |
| Feature works | Manual or E2E test | "User can login" |
不同的验收标准需要不同的验证方法:
| 标准类型 | 验证方法 | 示例 |
|---|
| 文件存在 | | "创建UserService.ts" |
| 文件已导出 | | "从index.ts导出" |
| 路由存在 | | "添加/users路由" |
| 类型存在 | | "添加User类型" |
| 函数存在 | | "添加calculateTotal()" |
| 依赖已安装 | | "安装lodash" |
| 模式已移除 | = 0 | "移除所有console.log" |
| TypeScript编译通过 | | "无类型错误" |
| 测试通过 | | "测试全部通过" |
| 功能正常 | 手动或E2E测试 | "用户可登录" |
Audit operates on
and may move tasks to
:
docs/todo/
├── done/ # Tasks claiming completion
│ └── {task_slug}/
│ ├── task.md # Has acceptance criteria
│ ├── implementation.md # Claims what was done
│ ├── verification.md # Should have proof
│ ├── .verified # REQUIRED - but may be false claim
│ └── .completed_at
│
├── pending/ # Where failed audits go
│ └── {task_slug}/
│ ├── task.md
│ ├── audit_failure.md # Why it failed audit
│ ├── .audit_failed # Signal
│ └── .audit_failed_at
│
└── audit_log/ # Audit history
└── {date}/
├── summary.md # Audit summary
├── passed.txt # List of passed tasks
└── failed.txt # List of failed tasks
docs/todo/
├── done/ # 标记为已完成的任务
│ └── {task_slug}/
│ ├── task.md # 包含验收标准
│ ├── implementation.md # 记录声称已完成的工作
│ ├── verification.md # 应包含验证证明
│ ├── .verified # 必填项 - 但可能是虚假标记
│ └── .completed_at
│
├── pending/ # 未通过审计的任务存放目录
│ └── {task_slug}/
│ ├── task.md
│ ├── audit_failure.md # 审计失败原因
│ ├── .audit_failed # 状态标记文件
│ └── .audit_failed_at
│
└── audit_log/ # 审计历史记录
└── {date}/
├── summary.md # 审计总结
├── passed.txt # 通过审计的任务列表
└── failed.txt # 未通过审计的任务列表
Step 1: List Tasks to Audit
步骤1:列出待审计的任务
Find all tasks in done/
查找done/目录下的所有任务
Step 2: For Each Task, Extract Criteria
步骤2:为每个任务提取验收标准
Read
and find the
section:
Acceptance Criteria
Acceptance Criteria
Step 3: Verify Each Criterion
步骤3:验证每个验收标准
mermaid
flowchart TD
A[Read Criterion] --> B{Type?}
B -->|File Exists| C["test -f {path}"]
B -->|Export| D["grep 'export.*Name' {index}"]
B -->|Function| E["grep 'function Name' {file}"]
B -->|Type| F["grep 'type Name' {file}"]
B -->|Route| G["grep '{path}' {router}"]
B -->|Dependency| H["grep '{pkg}' package.json"]
B -->|Pattern Gone| I["grep -r '{pattern}' = 0"]
B -->|Compiles| J["tsc --noEmit"]
B -->|Tests Pass| K["npm test"]
C --> L{Pass?}
D --> L
E --> L
F --> L
G --> L
H --> L
I --> L
J --> L
K --> L
L -->|Yes| M[Record PASS]
L -->|No| N[Record FAIL]
mermaid
flowchart TD
A[Read Criterion] --> B{Type?}
B -->|File Exists| C["test -f {path}"]
B -->|Export| D["grep 'export.*Name' {index}"]
B -->|Function| E["grep 'function Name' {file}"]
B -->|Type| F["grep 'type Name' {file}"]
B -->|Route| G["grep '{path}' {router}"]
B -->|Dependency| H["grep '{pkg}' package.json"]
B -->|Pattern Gone| I["grep -r '{pattern}' = 0"]
B -->|Compiles| J["tsc --noEmit"]
B -->|Tests Pass| K["npm test"]
C --> L{Pass?}
D --> L
E --> L
F --> L
G --> L
H --> L
I --> L
J --> L
K --> L
L -->|Yes| M[Record PASS]
L -->|No| N[Record FAIL]
Step 4: Handle Results
步骤4:处理验证结果
Ensure .verified exists
确保.verified文件存在
touch docs/todo/done/{task_slug}/.verified
touch docs/todo/done/{task_slug}/.verified
Update verification.md with proof
在verification.md中添加验证记录
echo "Verified: $(date)" >> docs/todo/done/{task_slug}/verification.md
echo "Verified: $(date)" >> docs/todo/done/{task_slug}/verification.md
Move to pending
移至pending目录
mv docs/todo/done/{task_slug} docs/todo/pending/
mv docs/todo/done/{task_slug} docs/todo/pending/
Add audit failure documentation
添加审计失败文档
cat > docs/todo/pending/{task_slug}/audit_failure.md << 'EOF'
cat > docs/todo/pending/{task_slug}/audit_failure.md << 'EOF'
-
File exists: front/services/SearchService.ts
-
TypeScript compiles
- FAILED: 3 type errors in related files
-
File exists: front/services/SearchService.ts
-
TypeScript compiles
Re-implement the task following the original acceptance criteria.
EOF
touch docs/todo/pending/{task_slug}/.audit_failed
echo "$(date -Iseconds)" > docs/todo/pending/{task_slug}/.audit_failed_at
touch docs/todo/pending/{task_slug}/.audit_failed
echo "$(date -Iseconds)" > docs/todo/pending/{task_slug}/.audit_failed_at
Remove false .verified if it existed
移除虚假的.verified文件(如果存在)
rm -f docs/todo/pending/{task_slug}/.verified
rm -f docs/todo/pending/{task_slug}/.verified
Example: Auditing a Task
示例:审计一个任务
Task: docs/todo/done/fuzzy_search/
任务:docs/todo/done/fuzzy_search/
task.md (excerpt)
task.md(节选)
Task: Fuzzy Search Implementation
Task: Fuzzy Search Implementation
Acceptance Criteria
Acceptance Criteria
Verification Commands
验证命令
1. MiniSearch installed
1. 验证MiniSearch已安装
grep '"minisearch"' front/package.json
grep '"minisearch"' front/package.json
Expected: "minisearch": "^6.0.0"
预期结果: "minisearch": "^6.0.0"
test -f front/services/SearchService.ts && echo "EXISTS" || echo "MISSING"
test -f front/services/SearchService.ts && echo "EXISTS" || echo "MISSING"
Expected: EXISTS
预期结果: EXISTS
3. Exported from index
3. 验证已从index.ts导出
grep "SearchService|createSearchIndex|fuzzySearch" front/services/index.ts
grep "SearchService|createSearchIndex|fuzzySearch" front/services/index.ts
Expected: export { createSearchIndex, fuzzySearch } from './SearchService';
预期结果: export { createSearchIndex, fuzzySearch } from './SearchService';
4. Function createSearchIndex exists
4. 验证createSearchIndex函数存在
grep "function createSearchIndex|const createSearchIndex|createSearchIndex =" front/services/SearchService.ts
grep "function createSearchIndex|const createSearchIndex|createSearchIndex =" front/services/SearchService.ts
Expected: match found
预期结果: 找到匹配内容
5. Function fuzzySearch exists
5. 验证fuzzySearch函数存在
grep "function fuzzySearch|const fuzzySearch|fuzzySearch =" front/services/SearchService.ts
grep "function fuzzySearch|const fuzzySearch|fuzzySearch =" front/services/SearchService.ts
Expected: match found
预期结果: 找到匹配内容
6. TypeScript compiles
6. 验证TypeScript编译通过
cd front && npx tsc --noEmit
cd front && npx tsc --noEmit
Expected: exit code 0
预期结果: 退出码为0
Audit Result: PASS
审计结果:通过
All criteria verified. Task remains in
with
confirmed.
所有标准均验证通过。任务保留在
目录中,且
标记已确认有效。
Example: Failed Audit
示例:审计未通过
Task: docs/todo/done/spell_routes/
任务:docs/todo/done/spell_routes/
task.md (excerpt)
task.md(节选)
Task: Wire SpellDetailView into Router
Task: Wire SpellDetailView into Router
Acceptance Criteria
Acceptance Criteria
Verification Commands
验证命令
1. Route in router config
1. 验证路由已添加到路由器配置
grep "spells/:slug|spell_detail" front/data/app-configs.ts
grep "spells/:slug|spell_detail" front/data/app-configs.ts
Result: NO MATCH
结果: 无匹配内容
2. Import in App.tsx
2. 验证App.tsx中已导入SpellDetailView
grep "SpellDetailView" front/app/App.tsx
grep "SpellDetailView" front/app/App.tsx
Result: NO MATCH
结果: 无匹配内容
3. Route element
3. 验证路由元素渲染SpellDetailView
grep "SpellDetailView" front/app/App.tsx | grep -i route
grep "SpellDetailView" front/app/App.tsx | grep -i route
Result: NO MATCH
结果: 无匹配内容
Audit Result: FAIL
审计结果:未通过
Route never implemented. Move to pending:
mv docs/todo/done/spell_routes docs/todo/pending/
mv docs/todo/done/spell_routes docs/todo/pending/
cat > docs/todo/pending/spell_routes/audit_failure.md << 'EOF'
cat > docs/todo/pending/spell_routes/audit_failure.md << 'EOF'
-
Route added: /spells/:slug
- FAILED: No route found in app-configs.ts
-
SpellDetailView imported in App.tsx
-
Route element renders SpellDetailView
- FAILED: No route element found
-
Route added: /spells/:slug
- FAILED: 在app-configs.ts中未找到该路由
-
SpellDetailView imported in App.tsx
-
Route element renders SpellDetailView
The task was marked done but no implementation exists.
SpellDetailView.tsx exists but was never wired into the router.
任务被标记为已完成,但实际未实现任何内容。
SpellDetailView.tsx文件存在,但从未接入路由器。
- Add spell_detail route to APP_ROUTES in app-configs.ts
- Import SpellDetailView in App.tsx
- Add <Route path="/spells/:slug" element={<SpellDetailView />} />
- Verify navigation works
EOF
- 在app-configs.ts的APP_ROUTES中添加spell_detail路由
- 在App.tsx中导入SpellDetailView
- 添加<Route path="/spells/:slug" element={<SpellDetailView />} />
- 验证导航功能正常
EOF
touch docs/todo/pending/spell_routes/.audit_failed
echo "2026-02-06T10:00:00Z" > docs/todo/pending/spell_routes/.audit_failed_at
rm -f docs/todo/pending/spell_routes/.verified
touch docs/todo/pending/spell_routes/.audit_failed
echo "2026-02-06T10:00:00Z" > docs/todo/pending/spell_routes/.audit_failed_at
rm -f docs/todo/pending/spell_routes/.verified
For auditing multiple tasks at once:
audit-done-tasks.sh
audit-done-tasks.sh
AUDIT_DATE=$(date +%Y-%m-%d)
AUDIT_DIR="docs/todo/audit_log/${AUDIT_DATE}"
mkdir -p "$AUDIT_DIR"
PASSED=()
FAILED=()
for task_dir in docs/todo/done/*/; do
task_name=$(basename "$task_dir")
echo "Auditing: $task_name"
# Run verification (implement per-task logic)
if verify_task "$task_dir"; then
PASSED+=("$task_name")
echo " PASS"
else
FAILED+=("$task_name")
echo " FAIL - moving to pending/"
mv "$task_dir" docs/todo/pending/
# Add audit_failure.md...
fi
done
AUDIT_DATE=$(date +%Y-%m-%d)
AUDIT_DIR="docs/todo/audit_log/${AUDIT_DATE}"
mkdir -p "$AUDIT_DIR"
PASSED=()
FAILED=()
for task_dir in docs/todo/done/*/; do
task_name=$(basename "$task_dir")
echo "Auditing: $task_name"
# 执行验证(需实现每个任务的验证逻辑)
if verify_task "$task_dir"; then
PASSED+=("$task_name")
echo " PASS"
else
FAILED+=("$task_name")
echo " FAIL - moving to pending/"
mv "$task_dir" docs/todo/pending/
# 添加audit_failure.md...
fi
done
cat > "$AUDIT_DIR/summary.md" << EOF
cat > "$AUDIT_DIR/summary.md" << EOF
Audit Summary: $AUDIT_DATE
审计总结: $AUDIT_DATE
- Passed: ${#PASSED[@]}
- Failed: ${#FAILED[@]}
- Total: $((${#PASSED[@]} + ${#FAILED[@]}))
- 通过: ${#PASSED[@]}
- 未通过: ${#FAILED[@]}
- 总计: $((${#PASSED[@]} + ${#FAILED[@]}))
$(echo "scale=1; ${#PASSED[@]} * 100 / (${#PASSED[@]} + ${#FAILED[@]})" | bc)%
EOF
printf '%s\n' "${PASSED[@]}" > "$AUDIT_DIR/passed.txt"
printf '%s\n' "${FAILED[@]}" > "$AUDIT_DIR/failed.txt"
$(echo "scale=1; ${#PASSED[@]} * 100 / (${#PASSED[@]} + ${#FAILED[@]})" | bc)%
EOF
printf '%s\n' "${PASSED[@]}" > "$AUDIT_DIR/passed.txt"
printf '%s\n' "${FAILED[@]}" > "$AUDIT_DIR/failed.txt"
Verification Patterns by Domain
按领域分类的验证模式
test -f front/components/{path}/{Component}.tsx
test -f front/components/{path}/{Component}.tsx
grep "export.*{Component}" front/components/{path}/index.ts
grep "export.*{Component}" front/components/{path}/index.ts
test -f front/hooks/use-{name}.ts
test -f front/hooks/use-{name}.ts
grep "{route}" front/app/App.tsx
grep "{route}" front/app/App.tsx
Style applied (check for className or styled-component)
样式已应用(检查className或styled-component)
grep "className=|styled." front/components/{path}/{Component}.tsx
grep "className=|styled." front/components/{path}/{Component}.tsx
API endpoint exists
API端点存在
grep "{endpoint}" back/src/api/{type}/routes/{type}.ts
grep "{endpoint}" back/src/api/{type}/routes/{type}.ts
Controller method exists
控制器方法存在
grep "{method}" back/src/api/{type}/controllers/{type}.ts
grep "{method}" back/src/api/{type}/controllers/{type}.ts
Content type schema
内容类型schema
test -f back/src/api/{type}/content-types/{type}/schema.json
test -f back/src/api/{type}/content-types/{type}/schema.json
test -f back/src/api/{type}/services/{type}.ts
test -f back/src/api/{type}/services/{type}.ts
Infrastructure Tasks
基础设施任务
Docker service defined
Docker服务已定义
grep "{service}" docker-compose.yml
grep "{service}" docker-compose.yml
Environment variable documented
环境变量已文档化
grep "{VAR_NAME}" .env.example
grep "{VAR_NAME}" .env.example
grep "{step_name}" .github/workflows/*.yml
grep "{step_name}" .github/workflows/*.yml
Data/Content Tasks
数据/内容任务
test -f front/data/{collection}/{slug}/data.ts
test -f front/data/{collection}/{slug}/data.ts
test -f static/public/{collection}/{slug}/{asset}
test -f static/public/{collection}/{slug}/{asset}
grep "{slug}" front/data/{collection}/index.ts
grep "{slug}" front/data/{collection}/index.ts
Common Audit Failures
常见审计失败情况
| Symptom | Likely Cause | Fix |
|---|
| File not found | Never created | Implement file |
| Not exported | Created but not added to index | Add export |
| TypeScript errors | Partial implementation | Fix types |
| Route not found | Added to wrong file | Add to correct router |
| Function missing | Different name used | Rename or implement |
| Tests failing | Implementation incomplete | Fix implementation |
| Dependency missing | Not installed | Run npm install |
| 症状 | 可能原因 | 修复方法 |
|---|
| 文件未找到 | 从未创建该文件 | 实现并创建文件 |
| 未导出 | 文件已创建但未添加到索引文件 | 添加导出声明 |
| TypeScript错误 | 实现不完整 | 修复类型错误 |
| 路由未找到 | 添加到了错误的文件 | 添加到正确的路由器配置文件 |
| 函数缺失 | 使用了不同的函数名称 | 重命名或实现该函数 |
| 测试失败 | 实现不完整 | 完善实现代码 |
| 依赖缺失 | 未安装该依赖 | 运行npm install命令 |
Audit Frequency Recommendations
审计频率建议
| Trigger | Frequency | Scope |
|---|
| Before release | Every release | All done/ tasks since last release |
| Weekly maintenance | Weekly | All done/ tasks |
| After agent session | Per session | Tasks marked done in session |
| Bug discovered | As needed | Related tasks |
| Onboarding | Once | All done/ tasks |
| 触发条件 | 频率 | 范围 |
|---|
| 发布前 | 每次发布 | 上次发布以来所有标记为done/的任务 |
| 每周维护 | 每周 | 所有done/目录下的任务 |
| Agent会话后 | 每次会话 | 会话中标记为已完成的任务 |
| 发现Bug时 | 按需 | 相关任务 |
| 新成员入职 | 一次 | 所有done/目录下的任务 |
Signal Files Reference
标记文件参考
| Signal | Location | Purpose |
|---|
| done/ | Task passed audit |
| pending/ | Task failed audit |
| pending/ | When it failed |
| done/ | When last verified |
| 标记文件 | 位置 | 用途 |
|---|
| done/ | 任务已通过审计 |
| pending/ | 任务未通过审计 |
| pending/ | 审计失败时间 |
| done/ | 上次验证时间 |
| File | Purpose |
|---|
audit_log/{date}/summary.md
| Audit session summary |
audit_log/{date}/passed.txt
| List of passed tasks |
audit_log/{date}/failed.txt
| List of failed tasks |
| Detailed failure info |
| 文件 | 用途 |
|---|
audit_log/{date}/summary.md
| 审计会话总结 |
audit_log/{date}/passed.txt
| 通过审计的任务列表 |
audit_log/{date}/failed.txt
| 未通过审计的任务列表 |
| 详细失败信息 |
Before marking an audit complete:
Add audit to CI pipeline for automatic verification:
.github/workflows/audit-tasks.yml
.github/workflows/audit-tasks.yml
name: Audit Done Tasks
on:
schedule:
- cron: "0 0 * * 0" # Weekly
workflow_dispatch:
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run task audit
run: ./scripts/audit-done-tasks.sh
- name: Fail if tasks failed audit
run: |
if [ -s docs/todo/audit_log/$(date +%Y-%m-%d)/failed.txt ]; then
echo "Tasks failed audit:"
cat docs/todo/audit_log/$(date +%Y-%m-%d)/failed.txt
exit 1
fi
name: Audit Done Tasks
on:
schedule:
- cron: "0 0 * * 0" # 每周执行
workflow_dispatch:
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run task audit
run: ./scripts/audit-done-tasks.sh
- name: Fail if tasks failed audit
run: |
if [ -s docs/todo/audit_log/$(date +%Y-%m-%d)/failed.txt ]; then
echo "Tasks failed audit:"
cat docs/todo/audit_log/$(date +%Y-%m-%d)/failed.txt
exit 1
fi