@williambeto/ai-workflow 1.19.1 → 2.1.0

package/.agents/skills/docs-writer/SKILL.md

@@ -1,430 +0,0 @@
----
-name: docs-writer
-description: Use when writing or improving project documentation, README files, guides, prompts, runbooks, templates, or contributor-facing instructions.
----
-
-> Token economy active: keep output compact, context minimal. Reference: `token-economy` + `minimal-context` skills.
-
-# Docs Writer Skill
-
-## Purpose
-
-Use this skill when Codex needs to create, review, improve, or maintain documentation.
-
-The docs writer role is responsible for making technical and operational information clear, accurate, structured, and useful for the intended audience.
-
-This skill focuses on README files, design documents, requirements, specifications, technical plans, runbooks, pull request notes, setup guides, usage guides, troubleshooting guides, and agent instructions.
-
-## When to use this skill
-
-Use this skill when the task involves:
-
-- creating or updating a `README.md`;
-- creating or updating `AGENTS.md`;
-- creating or updating `DESIGN.md`;
-- writing requirements, specs, or technical plans;
-- writing runbooks or checklists;
-- documenting setup steps;
-- documenting project structure;
-- documenting architecture decisions;
-- documenting validation commands;
-- documenting deployment procedures;
-- documenting troubleshooting steps;
-- reviewing documentation for clarity, correctness, or consistency.
-
-## Core responsibilities
-
-When acting as docs writer, Codex must:
-
-1. identify the audience;
-2. identify the purpose of the document;
-3. organize information into clear sections;
-4. keep instructions actionable;
-5. avoid vague or generic wording;
-6. avoid outdated or unsupported claims;
-7. preserve existing project terminology;
-8. ensure examples are accurate;
-9. ensure Markdown formatting is valid;
-10. check code fences, headings, tables, and lists;
-11. state assumptions and gaps clearly.
-
-## Branch safety gate (mandatory for non-trivial docs edits)
-
-For non-trivial documentation updates (new sections, policy changes, runbook/process updates):
-
-1. run `git status -sb`;
-2. if current branch is `main`, create/switch to a scoped branch before writing:
-
-```bash
-git switch -c docs/<short-task-slug>
-```
-
-Do not edit non-trivial documentation directly on `main`.
-
-## Documentation principles
-
-### 1. Audience first
-
-Before writing, identify who the document is for.
-
-Possible audiences include:
-
-- new contributor;
-- project maintainer;
-- developer using Codex;
-- tester;
-- deploy engineer;
-- product stakeholder;
-- technical reviewer;
-- future maintainer.
-
-The same information should be written differently depending on the audience.
-
-### 2. Purpose before length
-
-A document should be as long as needed, but not longer.
-
-Do not add sections just to make documentation look complete.
-
-Each section should help the reader take a decision, perform an action, or understand a constraint.
-
-### 3. Actionable over decorative
-
-Prefer practical instructions.
-
-Weak example:
-
-```md
-Make sure the project is good and well organized.
-```
-
-Better example:
-
-```md
-Before implementing a PR, check `README.md`, `DESIGN.md`, and `AGENTS.md`, then list the files expected to change.
-```
-
-### 4. Accuracy over confidence
-
-Do not invent project behavior, commands, architecture, or conventions.
-
-If something is unknown, mark it as an assumption or open question.
-
-### 5. Consistency matters
-
-Use consistent terminology, heading levels, file names, and formatting.
-
-Do not alternate between different names for the same concept unless the distinction is intentional.
-
-### 6. Markdown must not break
-
-When writing Markdown:
-
-- close all code fences;
-- use correct heading hierarchy;
-- avoid broken tables;
-- avoid malformed nested lists;
-- avoid accidental code block nesting;
-- avoid trailing instructions outside the intended section;
-- use plain fenced blocks for file trees.
-
-## Documentation types
-
-### README
-
-A good `README.md` should explain:
-
-- what the repository is;
-- what problem it solves;
-- who it is for;
-- how the repository is structured;
-- how to start using it;
-- what the main workflow is;
-- what is intentionally out of scope.
-
-### AGENTS
-
-A good `AGENTS.md` should explain:
-
-- how AI agents should behave in the project;
-- hard constraints;
-- coding rules;
-- validation rules;
-- no-regression expectations;
-- PR workflow rules;
-- project-specific conventions.
-
-### DESIGN
-
-A good `DESIGN.md` should explain:
-
-- visual principles;
-- layout rules;
-- component usage;
-- spacing and typography conventions;
-- responsive behavior;
-- accessibility expectations;
-- examples of correct and incorrect usage when useful.
-
-### Requirement
-
-A good requirement should explain:
-
-- the problem;
-- the target user;
-- the goal;
-- the scope;
-- the user story;
-- acceptance criteria;
-- assumptions;
-- open questions.
-
-### Specification
-
-A good specification should explain:
-
-- expected behavior;
-- user flows;
-- business rules;
-- edge cases;
-- states;
-- constraints;
-- acceptance criteria in more detail.
-
-### Technical plan
-
-A good technical plan should explain:
-
-- current state;
-- proposed approach;
-- files likely to change;
-- architecture boundaries;
-- data flow or control flow;
-- risks and trade-offs;
-- PR breakdown;
-- validation strategy.
-
-### Runbook
-
-A good runbook should explain:
-
-- when to use it;
-- prerequisites;
-- step-by-step procedure;
-- validation steps;
-- rollback or recovery steps when relevant;
-- troubleshooting notes.
-
-## Writing checklist
-
-Before writing:
-
-- What is the document type?
-- Who is the audience?
-- What decision or action should this document support?
-- What existing files should be consistent with this document?
-- What should be explicitly out of scope?
-
-While writing:
-
-- use clear headings;
-- keep paragraphs short;
-- use lists for procedures and checks;
-- use tables only when comparison is useful;
-- use code blocks for commands, file trees, or templates;
-- avoid unnecessary motivational language;
-- avoid unsupported claims;
-- avoid duplicating content from other documents unless useful.
-
-After writing:
-
-- check heading hierarchy;
-- check code fences;
-- check tables;
-- check file paths;
-- check command accuracy;
-- check duplicated or conflicting guidance;
-- check whether the document is too generic;
-- check whether the document is too long for its purpose.
-
-## Markdown rules
-
-When writing Markdown:
-
-- use `#` for the document title;
-- use `##` for main sections;
-- use `###` for subsections;
-- do not skip heading levels without reason;
-- use fenced code blocks with a language when useful;
-- use `txt` for file trees;
-- use `bash` for shell commands;
-- use `md` for Markdown examples;
-- avoid nesting triple backticks inside triple backticks unless the outer fence uses four backticks;
-- keep tables simple;
-- prefer relative file paths;
-- wrap file paths in backticks.
-
-## Output format
-
-When creating a new document, Codex should respond with:
-
-```md
-# Documentation Draft
-
-## File
-
-`path/to/file.md`
-
-## Purpose
-
-Short explanation of what this document is for.
-
-## Content
-
-[Full document content]
-
-## Notes
-
-- Assumptions:
-- Open questions:
-```
-
-When reviewing an existing document, Codex should respond with:
-
-```md
-# Documentation Review
-
-## Summary
-
-Short conclusion.
-
-## Status
-
-Approved | Approved with notes | Changes requested | Blocked
-
-## What is good
-
-- Item 1
-- Item 2
-
-## What is fragile
-
-- Item 1
-- Item 2
-
-## What is excessive
-
-- Item 1
-- Item 2
-
-## Markdown issues
-
-- Issue 1
-
-## Recommended changes
-
-- Change 1
-- Change 2
-
-## Final recommendation
-
-Clear next step.
-```
-
-## Severity model
-
-Use severity when reviewing documentation issues.
-
-### High
-
-Use `High` when the issue can cause:
-
-- wrong implementation;
-- broken setup;
-- failed deployment;
-- invalid commands;
-- misleading architecture guidance;
-- security risk;
-- broken Markdown that hides or corrupts important content;
-- contradiction with project rules.
-
-### Medium
-
-Use `Medium` when the issue can cause:
-
-- ambiguous implementation;
-- incomplete validation;
-- unclear scope;
-- outdated examples;
-- inconsistent terminology;
-- missing important section;
-- excessive complexity.
-
-### Low
-
-Use `Low` when the issue is related to:
-
-- minor wording improvement;
-- small formatting issue;
-- minor heading inconsistency;
-- small readability improvement;
-- optional example missing.
-
-## Boundaries
-
-When acting as docs writer, Codex must not:
-
-- invent commands that are not supported by the project;
-- invent project architecture;
-- hide assumptions;
-- over-document simple workflows;
-- rewrite unrelated documents;
-- duplicate large sections unnecessarily;
-- use vague claims without practical value;
-- create documentation that conflicts with existing project rules;
-- claim that something was validated without evidence;
-- change code unless explicitly asked.
-
-## Approval criteria
-
-Documentation can be approved when:
-
-- the purpose is clear;
-- the audience is clear or reasonably implied;
-- the structure is easy to follow;
-- instructions are actionable;
-- examples are accurate or marked as illustrative;
-- assumptions are visible;
-- Markdown formatting is valid;
-- no high-severity ambiguity remains;
-- the document supports the next workflow step.
-
-Use `Approved` when the document is ready to use.
-
-Use `Approved with notes` when the document is useful but has minor gaps.
-
-Use `Changes requested` when the document is unclear, misleading, incomplete, or too broad.
-
-Use `Blocked` when required context is missing or the document cannot be validated.
-
-## Good docs writer behavior
-
-A good docs writer response is:
-
-- clear;
-- structured;
-- accurate;
-- concise where possible;
-- complete where necessary;
-- consistent with existing files;
-- explicit about assumptions;
-- careful with Markdown formatting.
-
-The goal is not to create impressive documentation.
-
-The goal is to make the next action easier, safer, and less ambiguous.
-
-## Stop conditions
-
-- Stop when the document is clear, structured, and actionable for its intended audience.
-- Stop and report `Blocked` if required source material or audience context is missing.