goclaw-docs-audit

# GoClaw Docs Audit > Detect which GoClaw docs need updating when GoClaw source code changes. > Cross-check accuracy against GoClaw source docs (source of truth). ## Trigger `/goclaw-docs-audit` or `/goclaw-docs-audit <commit-range>` or `/goclaw-docs-audit <file1> <file2>` ## Usage - `/goclaw-docs-audit` — audit all changes since last audit (or last commit if first run) - `/goclaw-docs-audit HEAD~5..HEAD` — audit specific commit range - `/goclaw-docs-audit internal/agent/loop.go internal/channels/telegram/bot.go` — audit specific files ## GoClaw Source Path The skill needs access to the GoClaw source repository. Resolution order: 1. **`GOCLAW_SOURCE_PATH`** environment variable (set in shell or `.claude/settings.local.json`) 2. **Fallback:** `../goclaw/` (assumes `goclaw/` and `goclaw-docs/` share the same parent folder) If neither resolves to a valid git repo, ask the user for the path. **Contributor setup example:** ```bash export GOCLAW_SOURCE_PATH=/path/to/my/goclaw ``` Or in `.claude/settings.local.json`: ```json { "env": { "GOCLAW_SOURCE_PATH": "/path/to/my/goclaw" } } ``` ## Instructions When this skill is triggered, follow these steps exactly: ### Step 0: Resolve GoClaw Source Path Determine `$GOCLAW_SOURCE` using the resolution order above: 1. Check if `GOCLAW_SOURCE_PATH` env var is set and points to a valid git repo 2. Otherwise check if `../goclaw/` exists and is a valid git repo 3. If neither works, ask the user to set `GOCLAW_SOURCE_PATH` Use `$GOCLAW_SOURCE` for all subsequent steps where `../goclaw/` was referenced. ### Step 1: Identify Changed Files - If argument is a commit range (contains `..` or `HEAD`): run `git diff --name-only <range>` in `$GOCLAW_SOURCE` - If argument is file paths: use those directly - If no argument: 1. Read `.claude/skills/goclaw-docs-audit/.last-audit` for the last audit commit hash 2. If file exists: run `git diff --name-only <last-audit-hash>..HEAD` in `$GOCLAW_SOURCE` 3. If file doesn't exist (first run): run `git diff --name-only HEAD~1..HEAD` in `$GOCLAW_SOURCE` ### Step 2: Load Mapping Rules Read `mapping.json` from the same directory as this SKILL.md file. The mapping also includes `source_of_truth` pointing to `docs/` (relative to `$GOCLAW_SOURCE`) — use those authoritative docs to verify accuracy of goclaw-docs pages. ### Step 3: Match Changed Files to Docs For each changed file, check if its path matches any `pattern` in the mapping rules (use glob matching). Collect all matched `docs` pages and their `priority`. ### Step 4: Accuracy Check Against Source of Truth For each matched docs page, cross-reference with the corresponding `$GOCLAW_SOURCE/docs/*.md` file: - Read the relevant goclaw internal doc (e.g., `01-agent-loop.md` for agent changes) - Compare key facts (config fields, API signatures, behavior descriptions) against what the goclaw-docs page says - Flag any discrepancies as "Needs accuracy update" Source of truth mapping (`$GOCLAW_SOURCE/docs/`): | GoClaw Doc | Covers | |---|---| | `00-architecture-overview.md` | Overall architecture, component relationships | | `01-agent-loop.md` | Agent loop, reasoning, tool execution | | `02-providers.md` | LLM provider integrations | | `03-tools-system.md` | Tool registration, execution, built-in tools | | `04-gateway-protocol.md` | WebSocket/RPC protocol | | `05-channels-messaging.md` | Channel integrations | | `06-store-data-model.md` | Database schema, data model | | `07-bootstrap-skills-memory.md` | Bootstrap, skills, memory systems | | `08-scheduling-cron.md` | Cron jobs, scheduling | | `09-security.md` | Security, auth, permissions | | `10-tracing-observability.md` | OpenTelemetry, tracing | | `11-agent-teams.md` | Agent teams, delegation | | `12-extended-thinking.md` | Extended thinking feature | | `13-ws-team-events.md` | WebSocket team events | | `14-skills-runtime.md` | Skills runtime | | `15-core-skills-system.md` | Core skills system | | `16-skill-publishing.md` | Skill publishing | | `17-changelog.md` | Changelog | | `18-http-api.md` | HTTP/REST API | | `19-websocket-rpc.md` | WebSocket RPC methods | | `20-api-keys-auth.md` | API keys, authentication | ### Step 5: Check EN-VI-ZH Sync Status For each matched docs page in the goclaw-docs repo: - Get last modification date of the EN file (e.g., `getting-started/quick-start.md`) - Get last modification date of the VI file (e.g., `vi/getting-started/quick-start.md`) - Get last modification date of the ZH file (e.g., `zh/getting-started/quick-start.md`) - If VI/ZH is older than EN, or doesn't exist: mark as "Outdated" - If VI/ZH is same date or newer: mark as "Synced" Use `git log -1 --format=%cd --date=short -- <file>` to get last modification dates. ### Step 6: Generate Report Create a markdown report with this format: ```markdown # GoClaw Docs Audit Report **GoClaw changes:** `<commit-range or file list>` **Date:** YYYY-MM-DD ## Affected Docs Pages | Changed File | Affected Docs | Priority | |---|---|---| | internal/agent/loop.go | agents/*, core-concepts/agents-explained.md | High | ## Accuracy Check (vs $GOCLAW_SOURCE/docs/) | Docs Page | Source of Truth | Status | Notes | |---|---|---|---| | agents/creating-agents.md | 01-agent-loop.md | Accurate | — | | core-concepts/tools-overview.md | 03-tools-system.md | Discrepancy | Missing new tool type "x" | ## EN-VI-ZH Sync Status | EN Page | Last EN | Last VI | VI Status | Last ZH | ZH Status | |---|---|---|---|---|---| | getting-started/quick-start.md | 2026-03-07 | 2026-03-01 | Outdated | 2026-03-07 | Synced | ## Recommended Actions 1. Review `agents/creating-agents.md` — agent creation flow changed 2. Fix accuracy: `core-concepts/tools-overview.md` missing new tool type 3. Sync VI translation for `getting-started/quick-start.md` ``` ### Step 7: Save Report Save to `{goclaw-docs-root}/plans/reports/docs-audit-{YYYY-MM-DD}.md` or to the reports path provided by session context. ### Step 8: Update Last Audit Marker After saving the report, record the current HEAD commit hash of `$GOCLAW_SOURCE` so the next no-argument run starts from here: ```bash cd $GOCLAW_SOURCE && git rev-parse HEAD > <goclaw-docs-root>/.claude/skills/goclaw-docs-audit/.last-audit ``` The `.last-audit` file contains a single line: the commit hash. This file is gitignored. ## Key Rules - GoClaw source path is resolved via `GOCLAW_SOURCE_PATH` env var, fallback to `../goclaw/` (assumes same parent folder) - `$GOCLAW_SOURCE/docs/` is the **source of truth** for feature accuracy - Docs live in `goclaw-docs/` (EN at root, VI under `vi/`) - If no GoClaw repo found, ask user for the path - Always show: affected docs, accuracy check, AND EN-VI sync status - Group results by priority (High → Medium → Low)