write-doc
This writes a named coding artifact (a README, a findings note, a report) in the house voice from
a supplied template. Findings first, the right structure for its kind, plain words, no padding.
Does not invent results; it writes up what is verified.
When to use it
- Writing a README, a findings note, or a report. Those three types are the scope; there is
no other-document mode.
- The work is verified and needs to be written up, not condensed from an existing source.
- Skip it when the goal is to shorten an existing document; that is a summarize task, not a
write task.
The neighboring jobs route elsewhere:
- A decision that needs a durable record goes to
record-decision, not here.
- A deliberate shortcut goes to
debt-log, not here.
- Commit and PR text goes to
prepare-pr, not here.
- Session state for the next session goes to
handoff-session, not here.
Required inputs
- What the deliverable is: README, findings note, or report.
- The template for that type. Required: without a template to check against, stop and ask for
one rather than inventing a structure.
- The facts, decisions, or results to write up, with their basis.
- The audience and the level of detail they need.
Steps
- Take the structure from the template. A README opens with what it is and the one bar that
proves it works. A findings note puts the conclusion first, then support. A report states the
question, the finding, and the evidence, in that order.
- Write findings first. The conclusion or recommendation goes in the first sentence or two.
- Fill in support: evidence, context, and caveats. Keep each claim tagged with its basis (verified,
proposed, or unknown).
- Cut the rest. Drop openers, hedges, and wind-up phrases. Every sentence must change the reader's decision or go.
- Check against the template. Confirm the structure matches the type, claims are tagged, and the
prose is in the house voice.
Output format
The deliverable itself, formatted for its type. No wrapper or commentary around it; if the
deliverable is a markdown file, produce only the file content. Every claim carries its basis; a
rejected idea stays with its reason.
Stop conditions
- A reader unfamiliar with the work could use the document alone.
- No claim rests on assertion. If a fact is unverified, tag it as proposed or unknown.
- The document does not invent results. Write what is known; name gaps as gaps.
- The document matches its template. If no template was supplied, the run stopped at the
inputs instead of shipping an untested structure.
1---2name: write-doc3description: Use when writing a named coding artifact (a README, a findings note, a report) in the house voice from a supplied template. Produces a findings-first document with the right structure for its kind, plain words, and no padding.4---56# write-doc78This writes a named coding artifact (a README, a findings note, a report) in the house voice from9a supplied template. Findings first, the right structure for its kind, plain words, no padding.10Does not invent results; it writes up what is verified.1112## When to use it1314- Writing a README, a findings note, or a report. Those three types are the scope; there is15 no other-document mode.16- The work is verified and needs to be written up, not condensed from an existing source.17- Skip it when the goal is to shorten an existing document; that is a summarize task, not a18 write task.1920The neighboring jobs route elsewhere:2122- A decision that needs a durable record goes to `record-decision`, not here.23- A deliberate shortcut goes to `debt-log`, not here.24- Commit and PR text goes to `prepare-pr`, not here.25- Session state for the next session goes to `handoff-session`, not here.2627## Required inputs2829- What the deliverable is: README, findings note, or report.30- The template for that type. Required: without a template to check against, stop and ask for31 one rather than inventing a structure.32- The facts, decisions, or results to write up, with their basis.33- The audience and the level of detail they need.3435## Steps36371. Take the structure from the template. A README opens with what it is and the one bar that38 proves it works. A findings note puts the conclusion first, then support. A report states the39 question, the finding, and the evidence, in that order.402. Write findings first. The conclusion or recommendation goes in the first sentence or two.413. Fill in support: evidence, context, and caveats. Keep each claim tagged with its basis (verified,42 proposed, or unknown).434. Cut the rest. Drop openers, hedges, and wind-up phrases. Every sentence must change the reader's decision or go.445. Check against the template. Confirm the structure matches the type, claims are tagged, and the45 prose is in the house voice.4647## Output format4849The deliverable itself, formatted for its type. No wrapper or commentary around it; if the50deliverable is a markdown file, produce only the file content. Every claim carries its basis; a51rejected idea stays with its reason.5253## Stop conditions5455- A reader unfamiliar with the work could use the document alone.56- No claim rests on assertion. If a fact is unverified, tag it as proposed or unknown.57- The document does not invent results. Write what is known; name gaps as gaps.58- The document matches its template. If no template was supplied, the run stopped at the59 inputs instead of shipping an untested structure.
alawein