docs-plan

docs-plan

Discover what a project's documentation must cover, from the project's own evidence, and write the result to one durable artifact.

The artifact holds a ranked task list in three tiers and one user need per task. It also holds a typed inventory of every page, a coverage map, a delete list and an IA plan. Nothing here writes documentation prose.

Use this skill before writing or restructuring documentation. Use the docs-quality rules while writing individual pages.

Stop condition

Stop when the artifact file exists on disk and all of the following hold.

• Every top-level subcommand or exported entry point appears either in the task list or in the explicit out-of-scope list.
• Every shortlisted task carries a user need, a tier, a ranking signal, a mapped page or the literal missing, and an action.
• Every existing page carries a doc_type value, proposed or already declared.
• The delete list contains only pages that failed both delete signals.

Then stop. Do not write the pages. Do not apply the delete list without the maintainer saying so, because deleting documentation unattended is a different risk class from writing a page.

The evidence rule

Every claim in the artifact comes from the repository, its issue tracker, its logs, or a run you actually performed. Never from an existing docs page title, and never from a number you did not measure. Those two shortcuts are the way this procedure gets faked, and both have their own rule.

Procedure

Run the steps in order. Each names the output it must leave behind.

1. Declare the product shape

Read the docs config for one of cli, library, hosted-service or framework. Look in the mkdocs.yml extra table, a pyproject.toml tool table, or a docs.toml. If none is declared, infer one from the repository and write it into the config as part of this run.

Output: one shape value, recorded in the artifact header. Every first-steps threshold later branches on it. See references/tiers-and-types.md.