Audit Docs Skill

Analyze the gap between the codebase changes (features, tools, skills, settings) made since the last documentation update (or release tag) and current HEAD. Verify whether user documentation (website/ and docs/user/) accurately reflects these changes and maintains Korean-English translation parity.

🧭 Workflow Decision Tree

1. Run Automated Audit Script
   └─ python3 .agents/skills/audit-docs/scripts/audit_docs.py [--since <REF> | --release]
2. Inspect Code Changes vs Document Mapping
   ├─ Built-in Tools → docs/user/guides/builtin-tools.md
   ├─ Bundled Skills → docs/user/guides/skills.md
   ├─ Settings/Config → docs/user/guides/troubleshooting.md & getting-started/
   └─ Scenarios/Workflows → docs/user/scenarios/
3. Audit KO ↔ EN Translation Parity & Truncation
   └─ Check if EN ratio < 70% or headings mismatch
4. Verify ASD-STE100 Style Compliance
   └─ Check active voice, imperative verbs, sentence length <= 20-25 words
5. Output Structured Audit Report & Action Plan

Step 1: Run the Audit Script

Run the helper script to detect baseline commits, code changes, and doc parity:

# 1. Automatic mode: Compares against the last commit that touched docs/user/
python3 .agents/skills/audit-docs/scripts/audit_docs.py

# 2. Release mode: Compares against the latest Git release tag
python3 .agents/skills/audit-docs/scripts/audit_docs.py --release

# 3. Custom baseline: Compares against a specific branch or commit ref
python3 .agents/skills/audit-docs/scripts/audit_docs.py --since dev/0.9.x~10

# 4. JSON format for machine parsing
python3 .agents/skills/audit-docs/scripts/audit_docs.py --json --output audit_report.json

Step 2: Analyze Code Diffs & Map to Docs

Inspect code diffs between baseline and HEAD across five key architectural domains:

Verification Checklist:

• Were new skills added to bundled_skills without being listed in the Skills Catalog?
• Were new MCP tools or tool parameters added without reference entries?
• Were UI setting keys renamed or added without updating troubleshooting and setup guides?
• Were new execution modes (e.g., YOLO, Unsafe, Normal) added without documentation?

Step 3: Audit KO ↔ EN Translation Parity

A common pitfall is updating Korean documentation while leaving English documents as outdated skeletons.

Check the KO ↔ EN Documentation Parity Audit table from the script:

1. MISSING_EN: Korean document exists, but English counterpart does not exist. (Critical)
2. SEVERE_TRUNCATION (Ratio < 40%): English document is severely abbreviated or a placeholder stub. (High)
3. MODERATE_TRUNCATION (Ratio 40% ~ 70%): English document misses key tables, tips, or sections. (Medium)
4. OK (Ratio >= 70%): Content volume and structural depth match.

Step 4: Verify ASD-STE100 Style Guidelines

When writing or reviewing English documentation, enforce ASD-STE100 principles:

1. Sentence Length:
   • Procedural instructions: <= 20 words.
   • Descriptive statements: <= 25 words.
2. Imperative Verbs:
   • Begin instruction steps with active verbs (Specify, Configure, Inspect, Run).
3. Clarity and Precision:
   • Avoid ambiguous modals (should, might). Use must for requirements, can for capabilities.
   • Restrict consecutive noun clusters to 3 words or fewer.

Step 5: Generate the Final Audit Report

Structure the final audit report using this markdown format:

# 📋 Documentation Gap Audit Report

## 1. Audit Scope & Baseline

- Baseline: `<COMMIT_HASH>` (<SUMMARY>)
- Target Head: `<HEAD_HASH>`
- Audit Mode: `<AUTOMATIC | RELEASE | CUSTOM>`

## 2. Code Changes vs. Document Mapping Gaps

| Change Type | Component / File | Detected Code Change    | Affected Documentation    | Status      |
| ----------- | ---------------- | ----------------------- | ------------------------- | ----------- |
| New Skill   | `skill-name`     | Added to bundled_skills | `guides/skills.md`        | 🔴 Missing  |
| Tool Flag   | `browser`        | Added `--sandbox` arg   | `guides/builtin-tools.md` | ⚠️ Outdated |

## 3. Translation Parity Findings (KO ↔ EN)

- Total Files Audited: XX
- Truncated / Outdated EN Files: X
- Parity Gaps List:
  - `path/to/doc.md`: Ratio XX%, missing sections: [...]

## 4. Actionable Remediation Plan

1. [P0] Update `guides/skills.md` (KO & EN) to include `new-skill`.
2. [P1] Re-translate `path/to/doc.md` to ASD-STE100 standards.
3. [P2] Run `pnpm --filter libragent-docs build` to verify clean build.