df12-documentation-skills

Write and revise tutorials and how-to guides — the two practical, action-oriented kinds of documentation. Use this skill whenever the user asks to write, draft, structure, or fix a tutorial, a getting- started guide, a walkthrough, a lesson, a how-to, a task guide, a recipe, a procedure, or a troubleshooting guide. Also trigger when a document tries to both teach and get a job done at once, when a "tutorial" reads like a reference dump, when steps fail for readers, or when the user is unsure whether they need a tutorial or a how-to. The skill first classifies the document by user need (study versus work), then drives a test-the-path workflow: scope the journey or the goal, execute it end to end recording real output, draft to the right anatomy, edit out blurred boundaries, and hand off to reference and explanation. It is grounded in Diátaxis, Carroll's minimalism, Gagné's events of instruction, and cognitive load theory.

Groom and curate a *living* GIST (Goals, Ideas, Steps, Tasks) roadmap as it accretes work during execution — audit findings, code and design review follow-ups, dogfooding fixes, and new ideas. Use this skill whenever you are maintaining an existing roadmap rather than authoring one: when refactoring or re-architecting tasks have piled up and need consolidating into proper steps; when a hardening or refactoring phase has inflated into many single-task "steps"; when new feature ideas risk being buried among refactoring work, or refactoring work risks being dismissed as low value; when deciding what is genuine debt versus self-generating audit churn; or whenever a roadmap has grown and needs to be made legible again. This is the maintenance counterpart to the roadmap-doc skill, which authors a roadmap from design documents — read roadmap-doc for the GIST grammar, format, and anti-patterns this skill assumes.

Write and maintain a project's `CHANGELOG.md` following the Common Changelog style. Use this skill whenever the user asks to create, draft, update, rewrite, or review a changelog; add a release entry; record notable changes since the last tag; cut a release; promote a prerelease; or document a yanked release. Trigger on phrases such as "update the changelog", "add a changelog entry", "what changed since v1.2.0?", "draft release notes from git history", or "write CHANGELOG.md".

Create GitHub pull requests (PRs) with complete draft PR metadata, reviewer-focused descriptions, roadmap and issue references, execplan identification, and en-GB Oxford English. Use whenever Codex opens, drafts, revises, or prepares a pull request description or title for a branch.

Generate terms of reference documents that capture the problem space — domain, market, users, job-to-be-done, scope, constraints, and open questions — before any solution work begins. Use this skill whenever the user asks to write, draft, or produce a terms of reference, project charter, product brief, problem statement, vision and scope document, domain knowledge document, or "what is this for" document. Also trigger when the user starts a new project without an established brief, wants to capture domain knowledge from a subject-matter expert, needs to draw explicit scope boundaries before technical design, or asks to elicit and document the rationale for a system. The skill drives an elicitation-led workflow: prior-art discovery, gap analysis, structured interview, drafting, editing, and handoff to the design and roadmap skills. It produces documents in the style of df12 Productions — precise, evidence-grounded, and free of aspirational fluff.

Generate development roadmaps from design documents, RFCs, and ADRs found in a repository or provided with the prompt. Use this skill whenever the user asks to create, draft, write, or generate a roadmap, execution plan, delivery plan, or development plan for a software project — especially when design documents, RFCs, or ADRs are available as source material. Also trigger when the user asks to turn a design document or set of RFCs into actionable work items, or to plan the build order for a system described in technical documentation. Trigger even for partial requests such as "plan the next phase" or "break this design into tasks" when design documentation is present.

Generate rigorous technical design documents from a problem statement or product brief. Use this skill whenever the user asks to produce a system design, technical specification, architecture document, design document, or product design — whether from scratch, from an existing brief, or by expanding a rough concept into a full specification. Also trigger when the user asks to "write a design doc", "spec this out", "produce an architecture document", "design this system", or provides a problem statement and expects a structured technical output. The skill drives a multi-phase workflow: research, outline, planning, drafting with external artefacts, Mermaid diagram validation, and a mandatory editing pass. It produces documents in the style of df12 Productions design documents — precise, evidence-grounded, and free of fluff.

Write and apply Git commit messages. Use this skill whenever committing code, staging a commit, writing a commit message, or when the user says "commit", "git commit", "save my changes", or asks to describe what changed. Also trigger when reviewing staged changes before committing. This skill enforces file-based commit messages — never pass messages via `-m`.

Voice and copy style enforcement for df12 Productions. Use this skill whenever writing, editing, or reviewing marketing copy, landing pages, product descriptions, white papers, migration guides, release announcements, blog posts, README openers, or any other public-facing prose for df12 Productions or its products (Netsuke, Weaver, rstest-bdd, Zamburak, Wildside, Concordat, and others). Also trigger when the user asks to write "in the df12 voice", mentions the Logisphere crew or mascot characters, or requests copy that follows the "serious tools, playful worlds" ethos. This skill applies to all df12 product copy and should be used even for short-form content like taglines, feature bullets, changelogs, and social media posts.

Generate README files for projects in the df12 Productions house style

Enforce British English using Oxford spelling conventions, permit outwith and caveat where appropriate, and use the Oxford comma only when it improves clarity.