Documentation, Prose, Agent Instructions, & Pull Requests (flow-docs)

Write clear, accurate, zero-bloat technical documentation, user guides, agent instruction files (AGENTS.md, SKILL.md, OKF knowledge chapters), commit messages, changelogs, and pull requests.

Operational Modes (/flow:docs [mode])

• write — Author or update READMEs, user guides, module documentation, or agent skills using manifest-driven source coverage ([k/N files documented]).
• validate — Audit documentation and .agents/bundles/ for cold-reader comprehension, primary-source path/to/file::Symbol accuracy, broken links, and prose sediment.
• capture — Distill validated architectural and operational patterns from code and completed flows into .agents/bundles/knowledge/ and user-facing docs/.
• sync — Reconcile documentation claims and examples against live repository signatures and configuration.
• pr — Draft or update pull request titles, ## Summary + ## Key Changes bodies, signed commits, and release changelogs.

Core Writing & Anti-Bloat Rules

• Pass the Cold-Reader Comprehension Test. Every document must be understandable on the first read by a fresh engineer or isolated zero-context agent with no prior session history. Lead with purpose, public interface, concrete examples, and invariants.
• Read source before writing ([k/N files documented]). Enumerate the in-scope files first, read every file completely, and anchor claims to path/to/file::Symbol. Never guess behavior from filenames or function names.
• State rules plainly with a one-line Reason:. Write direct, present-tense sentences. When documenting a constraint or design choice, state the rule followed by Reason: <why>.
• Eliminate AI slop, buzzwords, and chronological sediment.
  • Never use promotional adjectives (seamless, robust, comprehensive, pivotal, delve, leverage, blazingly fast), decorative adverbs (seamlessly, effortlessly, obviously), negative parallelisms ("not just X, but Y"), formulaic transitions ("Moreover", "Furthermore"), or superficial participle tails ("...ensuring reliability").
  • Never use artificial numbered buzzword labels or inflated metaphors ("engineering lawbooks", "causal waterfall", "zero-tolerance"). Name components and headings semantically so counts never break when items change.
  • Never leave chronological sediment ("Added in v2", "Previously we used X") inside current-state documentation or specs. History belongs in CHANGELOG.md and .agents/bundles/log.md.
• Never leak internal workflow ceremony or private paths. Keep PRs, commits, changelogs, tests, and docs free of finding counts, task/finding IDs (ORA-001, test_task_1_2_*), workflow mechanics (checkpoint.phase, subagent names), ## Verification command logs, ## Merge Danger blocks, ASCII file/call trees, or local workstation paths.

Reference Guides

Workflow

1. Select Target & Reference:
   • For READMEs, user guides, module/API docs, or doc audits, load references/prose-and-documentation.md.
   • For AGENTS.md, SKILL.md, subagents, or .agents/bundles/knowledge/ chapters, load references/agent-context.md.
   • For PRs, commits, changelogs, or code review comments, load references/prs-commits-and-changelogs.md.
2. Build Manifest & Shard Primary-Source Authoring:
   • List every file in scope ([0/N files documented]) and read each implementation file before drafting prose.
   • When documenting or syncing >= 2 domains, subsystems, or chapters (/flow:docs write | capture | sync), fan out isolated per-domain or per-chapter documentation subagents so each file receives thorough, runnable, code-verified examples rather than a compressed summary.
3. Draft in Present Tense to Match Target Length & Hierarchy:
   • Keep user guides focused on a single concept (<= 200 lines), leading with a runnable example and expected output.
   • Keep living specs (specs/<flow_id>/spec.md, chapters/index.md, chapters/<ch_id>/spec.md), .agents/bundles/knowledge/** chapters, and user docs/ strictly in present tense—stating current verified reality, remaining chapters, and the full plan with zero Revision History sections or historical layering.
   • Keep SKILL.md files <= 200 lines (< 24,000 bytes), <!-- truth: start --> blocks <= 40 lines, and bundle bodies free of standalone --- horizontal rules, disclosing deep reference material into references/*.md.
4. Verify & Prune:
   • Strip puffery, chronological sediment, duplicate cache lines, and workflow ceremony, then verify all links and examples (make lint).

Guardrails

• Conceptual Diagrams Only in docs/: Keep Mermaid diagrams in user-facing docs/ and README.md conceptual (4–6 nodes focused on the user mental model). Place detailed module/implementation diagrams in .agents/bundles/knowledge/architecture/.
• Single Source of Truth: Link to canonical rules rather than duplicating them across files.
• Calm, Matter-of-Fact Tone: Never use exclamation marks (!) or dismissive language in documentation, PR bodies, or code reviews.

Validation

• Confirm every manifest item is covered ([N/N files documented]) and every technical claim cites a verified source (path/to/file::Symbol).
• Confirm PR bodies contain only ## Summary and ## Key Changes and every PR # or Issue # in chat is a clickable Markdown link.
• Confirm all relative Markdown links resolve on disk and make lint exits 0.

Example

Invoke /flow:docs write to document a module with [4/4 files documented] coverage tracking, /flow:docs validate to audit .agents/bundles/ and docs/ for stale symbols or prose bloat, or /flow:docs pr when preparing a pull request in /flow:finish.