goclaw-docs-audit

name	goclaw-docs-audit
description	Detect which GoClaw docs pages need updating when source code changes.
argument-hint	[commit-range|file1 file2 ...]
metadata	{"author":"goclaw","version":"2.0.0"}

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:

export GOCLAW_SOURCE_PATH=/path/to/my/goclaw

Or in .claude/settings.local.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:

# 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:

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)