astroclaw-refactor-docs

Files (1)

• SKILL.md

SKILL.md (first lines)

# Astroclaw Refactor Docs

## Overview

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

This skill builds on `astroclaw-docs`: 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:

- Desired page type, such as topic page, guide, reference, or troubleshooting.
- Specific goals, such as shorter main page, move details to reference pages, or
  align with current CLI behavior.
- 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:

- Topic or guide pages cover the 80/20 path, decisions readers must make, safe
  setup, smallest reliable verification, common failures, and links onward.
- Reference pages cover exhaustive fields, defaults, enums, limits, precedence
  rules, API contracts, narrow internals, and rare debugging details.
- Troubleshooting pages start from observable symptoms and map to checks,
  causes, and fixes.

## Workflow

### 1. Load the doc standard

Read `../astroclaw-docs/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 `astroclaw-docs`.

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

- 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
  readers need them to complete the workflow.

### 3. Preserve and audit existing facts

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

- Config fields, flags, commands, slash commands, env vars, defaults, enums,
  nullable values, and constraints.
- Precedence rules, fallback behavior, caps, limits, rate limits, timeouts,
  lifecycle states, queueing behavior, and compatibility rules.
- Auth, permission, approval, sandbox, safety, privacy, and destructive-action
  behavior.
- Setup requirements, supported versions, dependencies, operating systems,
  credentials, and account requirements.
- 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:

- Public schema, plugin manifest, generated config docs, or exported types for
  config fields.
- CLI implementation, slash-command handlers, help text, and command tests for
  commands and flags.
- Runtime source and tests for lifecycle, queueing, permission, fallback,
  timeout, and provider behavior.
- Protocol docs, SDK facades, and contract tests for APIs and plugin surfaces.
- Existing docs only as secondary evidence unless the target is purely
  conceptual.

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:

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

From P1R4N351/astroclaw, MIT.

More from P1R4N351/astroclaw