All Skills
/to-docs Phase 6: Technical Documentation

The /to-docs Skill

Transforms verified code into purpose-driven technical documentation adhering strictly to the Diátaxis framework and operational delivery artifacts.

"Can you use the result? Can you use the method for some other problem? It is sad to work for an end that you do not desire." — George Pólya, How to Solve It (1945)
TERMINAL OR CHAT PROMPT 
/to-docs @docs/spec/checkout-spec.md Author How-To guide for integrating checkout webhook and document reference schemas.

What it does

to-docs translates completed, verified software systems into clear, purpose-driven technical documentation adhering to the Diátaxis Framework (diataxis.fr). It enforces strict quadrant separation across Tutorials (learning journeys for beginners), How-To Guides (task-oriented recipes and runbooks), Reference (austere descriptions of APIs, schemas, and error codes), and Explanation (discursive architectural context and ADR rationale).

It also authors essential operational delivery artifacts: Pull Request descriptions, Keep a Changelog entries, audience-tailored Release Notes, and Blameless Postmortems. It inspects verified code directly ([file:line]) before writing to eliminate hallucinated flags or non-existent parameters. It refuses to modify application code.

When to reach for it

Where the work currently lives decides whether this is the right skill:

The work is… Reach for
Implementation verified & reviewed (verdict GO) ready for user/developer docs /to-docs @docs/spec/{slug}-spec.md
A completed branch ready for a comprehensive Pull Request description /to-docs (PR Description)
A new release tag needing structured Keep a Changelog entries /to-docs (CHANGELOG.md)
An incident retrospective after production outage or major regression /to-docs (Blameless Postmortem)
Designing internal backend database schemas, ports, or DTO contracts /to-spec

Prerequisites

  • Verified Codebase: Feature must be implemented and passing tests before writing user-facing guides or API references.
  • Source-Grounded Truth: The agent MUST inspect real code (view_file / grep_search) to verify exact signatures and flags.
  • Strict Documentation-Only Scope: Modifying production source code or altering tests is strictly prohibited.

What one run does

A single documentation run follows four structured phases:

  1. Audit & Clarify: Identifies target audience and selects exactly ONE Diátaxis quadrant (Tutorial, How-To, Reference, Explanation) OR one operational delivery format (PR description, Changelog, Release Notes, Postmortem).
  2. Design & Outline: Presents a clear structural outline tailored to the selected quadrant.
  3. Source-Grounded Drafting: Inspects real source code ([file:line]) and git history to ensure 100% technical truth. Verifies all code snippets are copy-paste runnable with clearly marked dummy credentials.
  4. Persist Output: Saves document to its canonical directory adhering to DOCS-TEMPLATE.md and offers to record milestones to memory.instructions.md via /to-memory.

Common questions

Why can't I combine a Tutorial, API Reference, and Explanation into one README?

Mixing Diátaxis quadrants confuses beginners with dense reference tables, buries actionable steps under discursive theory, and bloats documents. Pure, focused documents are significantly easier to read and maintain.

What is the Source-Grounded Verification Mandate?

Code often refines field names, flags, or error codes during implementation. Documenting from training memory or early specifications produces broken code examples. The agent must inspect actual repository code before documenting.

It's working if

  • The generated document belongs strictly to 1 Diátaxis quadrant or operational delivery format.
  • All CLI flags, DTO fields, and parameter tables match actual source code verified on disk.
  • All code snippets are complete and copy-paste runnable, with zero lazy placeholders (// ... setup here).
  • Never exposes real API keys or secrets, utilizing clearly marked dummy placeholders.
  • It modifies zero application code in /src or /lib.

Where it fits

to-docs is Phase 6 in the main idea-to-ship pipeline: 

/to-explore → /to-prd → /to-spec → /to-clarify → /to-plan → 🛑 PAUSE → /to-code → /to-review → 📚 /to-docs

It is invoked after /to-review issues a verdict GO. Once user and developer documentation is published, it offers to save the milestone to persistent memory via /to-memory.