docs-writer

Purpose

Writes and maintains project documentation that matches the code and follows a writing profile.

Source Skill purpose

When to use it

Use docs-writer when user-visible behavior changes or project documentation must be created, updated or audited. Create mode writes a document for a named reader and goal. Update mode follows a change range to every document it makes stale, while audit mode checks the set and repairs supported drift. The evidence script verifies quoted commands, paths, flags, configuration keys and repository links against the actual project. A writing profile controls sentence and paragraph length. Claims without a trace are marked unknown rather than invented.

The writing pass begins by reading the actual code before quoting its interfaces. It keeps an existing document's structure and edits the smallest relevant span rather than reformatting unrelated pages. The evidence checker follows internal links and verifies named commands, flags and configuration keys. The writer then reviews readability findings that a script can only flag for human judgment. Its final report names each edited document and remaining warning.

Source Skill purpose

How it works

Steps of the skill, in source order

Source Flow

Define reader and mode Choose create, update or audit, and name the document's reader and goal. For an update with no user-visible change, report docs: not_applicable and stop.
Source Flow
Find affected documents Search documentation for changed names, flags, keys and paths.
Source Flow
Write precise prose Edit the smallest span under the writing profile, placing actions first.
Source Flow
Prove references Run the evidence checker from the project root on every changed document; it exits 0 only when every quoted claim exists in the project. Correct unsupported references.
Source Flow
Judge readability Review the profile's judged findings that a script cannot decide alone.
Source Flow
Report document work List changed documents, evidence results and any remaining writing warnings.
Source Flow

Key rules

Run the evidence checker on every document created or changed.
Source Hard rules
Read project code before naming a command, flag, path or key.
Source Hard rules
Follow the repository's selected writing profile.
Source Hard rules
Mark an untraceable fact unknown rather than inventing it.
Source Hard rules
Preserve the document's structure and change the smallest necessary span.
Source Hard rules

Output and gate

Output

Report the writing mode, changed documents, evidence verdict and remaining warnings.
Source Output

Gate

The skill definition states no gate rule.

Source Skill definition

Source