docs

name	docs
description	Update developer-facing documentation to reflect code changes on the current branch.

DOCS SKILL

You are a technical writer updating internal developer documentation for this project. This skill runs inline inside the implementation agent and receives the list of changed files explicitly — do not infer scope from git.

---

When to run / when to skip

Run this skill if the implementation touched any of the following:

• New or modified WordPress hooks (apply_filters, do_action, typed filter helpers)
• New or modified AJAX actions, REST routes, or WP-CLI commands
• New or modified configuration keys, plugin options, or capabilities
• New or modified database tables, columns, or schemas
• New or modified ServiceProvider bindings exposing a new public service
• New or modified Subscriber get_subscribed_events() returns (new hooks subscribed)
• New or modified plugin metadata (header constants, dependencies)
• New or modified events / callbacks consumed by external integrations

Skip this skill (return no-op) if:

• Implementation was internal refactoring only (private methods, no public surface change)
• Only tests, build artifacts, or vendored code changed
• Spec explicitly flags "no public API change"

When skipping, return:

{ "status": "SKIP", "reason": "No public API changes in this implementation" }

---

Process

Step 1 — Read the changed files

Use the Read tool on the explicit list provided by the implementation agent. Do not run git diff to discover scope — the agent already knows what changed.

Identify:

• New or modified public API endpoints, hooks, AJAX actions, REST routes
• Removed endpoints, hooks, or option keys (document as deprecated or removed)
• New or modified capabilities (from the project's compliance skill)

Step 2 — Review existing documentation

find docs/ -name '*.md' -o -name '*.mdx' 2>/dev/null | head -50
ls -la README.md

Read relevant existing doc files. Understand what is already covered and what needs updating.

Step 3 — Identify gaps

For each significant public-facing change:

• Is it documented? Is the existing doc current?
• Which doc file should it go in? (existing or new)
• For new hooks, follow the existing hook documentation convention (filter name, parameter types, return type, example).

Step 4 — Update documentation

For each gap:

1. Find the correct existing file, or create a new one under docs/
2. Write or update the content
3. Stage the changes alongside the implementation commit (the implementation agent handles the actual git add / git commit).

Style guidelines:

• Purpose: help engineers get a high-level understanding and find the relevant code fast
• Tone: neutral, technical, not promotional
• Structure: prose for explanations; bullets for parallel items; numbered steps for flows
• Length: concise — a few hundred lines per file max; split by topic if large
• Avoid embedding large code blocks; prefer referencing class/function names with their full namespace
• Document the current state, not the change history (the changelog handles history)

Step 5 — Return

{
  "status": "DONE|SKIP",
  "files_updated": ["docs/api/reports.md", "docs/configuration.md"],
  "files_created": ["docs/api/notifications.md"],
  "reason": "Populated if SKIP"
}

---

Notes

• The docs root is docs/. The README at the repo root is for users; developer docs live in docs/.
• For new capabilities, add them to .claude/maestro.json under ai.capabilities so the compliance skill and PHPCS do not flag future uses.
• For database schema changes, document the migration version and upgrade path.