doc-gardening

Doc Gardening

Maintain the per-package documentation graph after code changes. This skill handles both generating docs for new packages and updating stale docs for existing ones.

If $ARGUMENTS is a specific package path (e.g., round or lib/tree), scope work to that package only. If $ARGUMENTS is all or empty, scan the entire repo.

Phase 1: Detect Changes

Determine what needs attention.

For scoped runs (specific package):

• Read the package's .go files and existing CLAUDE.md (if any).
• Determine if new or stale.

For full runs (all or no argument):

# Find packages missing CLAUDE.md
find . -name '*.go' -not -path './.git/*' -not -path './vendor/*' \
  -not -path './tools/*' | sed 's|/[^/]*$||' | sort -u | while read dir; do
    [ ! -f "$dir/CLAUDE.md" ] && echo "MISSING: $dir"
  done

# Find packages with Go changes on current branch
git diff --name-only main...HEAD -- '*.go' | sed 's|/[^/]*$||' | sort -u

Classify each affected package:

• New — has .go files but no CLAUDE.md.
• Stale — has CLAUDE.md but Go source changed since last update.

Phase 2: Read Package Sources

For each affected package, gather:

1. doc.go (if exists) — package purpose.
2. Key exported types and interfaces (read primary .go files, use go doc).
3. Import statements — which repo packages it imports.
4. README.md (if exists) — existing deep docs to link.
5. Actor message flows — search for Tell/Ask calls, outbox message types, FSM event types, and lib/actormsg marker interfaces that cross package boundaries. List concrete Go type names for each send/receive direction.

Use the Explore agent for packages with many files, or direct Read/Grep for small packages. Be thorough — per-package docs must be accurate, not guessed.

Message tracing tips:

• Search for Tell( and Ask( calls to find outbound messages.
• Search for types implementing VTXOActorMsg, RoundReceivable, or other lib/actormsg marker interfaces to find cross-boundary message types.
• Check FSM transition functions for outbox event types (emitted as side effects).
• Check EventRouter dispatch registrations in serverconn for ingress routing.