doc-with-usage-example

name	doc-with-usage-example
description	WHEN/WHERE/WHO: [Scheduling: Use when: the user asks to create or update documentation. Applies to: markdown documents, READMEs, guides, and runbooks] HOW: [Structural: Helps with: producing docs that always include 5W1H context and a copy-exec Usage Example] WHY: [Scheduling: Provides structured workflow execution to prevent errors and ensure standards.]

Document with Usage Example

Who

Developers, maintainers, and agents who create or revise technical documentation.

What

Produce documentation that is immediately actionable by always including a Usage Example section users can copy and execute, while organizing core context with the 5W1H structure.

When

• The user asks to create, draft, or update documentation.
• The document explains how to use a command, script, API, or workflow.
• The user needs higher confidence through runnable examples.

Where

• Markdown docs such as README.md, docs/*.md, and operational guides.
• Chat responses when no target file path is provided.

Why

• 5W1H keeps documentation complete and understandable.
• A copy-exec Usage Example reduces ambiguity and speeds adoption.
• Concrete examples increase confidence more than abstract instructions.

Inputs

• Target document path or output destination.
• Topic/workflow that the document must explain.
• Required commands, parameters, and expected results.

Output (Logical Evidence)

A document section set that includes:

• 5W1H coverage: Who, What, When, Where, Why, How.
• A dedicated ## Usage Example section with copy-exec snippets.

Optimization Readiness

• Failure Signals: The document lacks a usage example, examples are not executable, 5W1H coverage is incomplete, or the example drifts away from the documented environment.
• Evidence To Collect: Draft docs, usage snippets, consistency checks, and examples showing how the copy-exec section improved comprehension or execution readiness.
• Safe Mutation Boundaries: Refine 5W1H prompts, usage-example structure, and validation guidance without changing the core requirement to include an executable example.
• Acceptance Criteria: Accept revisions only if the final document includes a clear Usage Example, keeps the narrative aligned with the example commands, and remains executable as written.
• Rejected Revision Handling: Record non-executable examples, placeholder-only commands, and missing-5W1H drafts so they are not repeated.
• Transfer Check: Verify the workflow still works for READMEs, runbooks, and operational guides.
• Stop Rule: If the environment, expected result, or command details are unclear, stop and ask before drafting the document.

Constraints (Logical Boundaries)

• Always include a section titled exactly ## Usage Example.
• Ensure examples are executable as written (no placeholder-only commands unless explicitly labeled).
• Keep examples aligned with the documented environment and paths.
• If details are missing or conflicting, do not guess.

One More Thing

If anything is unclear, missing, or conflicting, stop and ask the developer before proceeding.

How (Structural Workflow)

1. Gather the minimum context: audience, goal, environment, and expected outcome.
2. Draft the document using 5W1H headings (Who/What/When/Where/Why/How).
3. Add ## Usage Example with at least one copy-exec command block and brief expected result.
4. Validate consistency between narrative steps and the example commands.
5. Deliver to the requested file or return in chat.