openclaw-refactor-docs skill

OpenClaw Refactor Docs

Overview

Use this skill when the user gives a target OpenClaw docs page and asks to rewrite, refactor, reorganize, split, shorten, or improve it.

This skill builds on technical-documentation: use that skill for style, page types, structure, examples, discoverability, and verification. This skill adds the rewrite workflow needed to avoid losing accurate behavior during a major docs refactor.

Inputs

Required:

• A target docs page path, such as docs/plugins/codex-harness.md.

Optional:

align with current CLI behavior.

• Desired page type, such as topic page, guide, reference, or troubleshooting.
• Specific goals, such as shorter main page, move details to reference pages, or

• Related source files, schemas, commands, tests, specs, or PRs.

If the target page is missing or ambiguous, ask one concise question before editing. Otherwise, proceed.

Working Contract

Refactor the target page to be more useful, concise, and comprehensive within its stated scope.

Do not treat a rewrite as permission to discard behavior facts. Preserve, verify, move, or explicitly retire existing material. Incorrect docs are worse than verbose docs.

Prefer this split:

setup, smallest reliable verification, common failures, and links onward.

• Topic or guide pages cover the 80/20 path, decisions readers must make, safe

rules, API contracts, narrow internals, and rare debugging details.

• Reference pages cover exhaustive fields, defaults, enums, limits, precedence

causes, and fixes.

• Troubleshooting pages start from observable symptoms and map to checks,

Workflow

1. Load the doc standard

Read ../technical-documentation/SKILL.md first. Apply its page-type, style, examples, navigation, and verification guidance throughout the refactor.

Run pnpm docs:list when available, then read only the target page and the likely entry points, references, or related pages needed for the refactor.

2. Classify the page

Before editing, decide the intended page type from technical-documentation.

If the current page mixes page types, choose the main page type and plan where the other material belongs:

readers need them to complete the workflow.

• Move exhaustive contracts to an existing or new reference page.
• Move symptom-driven material to an existing or new troubleshooting page.
• Move narrow setup workflows to a guide when they interrupt the main path.
• Keep concise routing, decision, and safety details in the main page when

3. Preserve and audit existing facts

Create a working inventory from the old page before rewriting. Include:

nullable values, and constraints.

• Config fields, flags, commands, slash commands, env vars, defaults, enums,

lifecycle states, queueing behavior, and compatibility rules.

• Precedence rules, fallback behavior, caps, limits, rate limits, timeouts,

behavior.

• Auth, permission, approval, sandbox, safety, privacy, and destructive-action

credentials, and account requirements.

• Setup requirements, supported versions, dependencies, operating systems,

• Error messages, troubleshooting symptoms, diagnostics, and recovery steps.
• Examples, expected output, command routing tables, and cross-links.

For each fact, choose one outcome:

• Keep it in the refactored target page.
• Move it to a specific existing page.
• Move it to a specific new page.
• Delete it because current source proves it is obsolete or out of scope.

Do not infer defaults, permissions, policy, timeout behavior, or safety posture from names or intent. Verify them.

4. Find source of truth

Use the nearest authoritative source for each behavior-sensitive claim:

config fields.

• Public schema, plugin manifest, generated config docs, or exported types for

commands and flags.

• CLI implementation, slash-command handlers, help text, and command tests for

timeout, and provider behavior.

• Runtime source and tests for lifecycle, queueing, permission, fallback,

conceptual.

• Protocol docs, SDK facades, and contract tests for APIs and plugin surfaces.
• Existing docs only as secondary evidence unless the target is purely

If a page promises a reference, compare its tables against the schema, manifest, CLI help, generated docs, or exported types. Missing public fields, defaults, precedence rules, caps, or side effects are correctness bugs.

5. Plan moved material

When moving detail out of the target page, record the destination before editing:

doc-schema-version: 1, and read_when hints.

• Existing page: name the page and section.
• New page: choose the page type, slug, title, frontmatter summary,