grounded-writing · diff
git:20260924.ba03969 to git:20261020.0bd44a0
56 added, 109 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: grounded-writing
description: Use when drafting or reviewing public developer documentation, other text the user will publish or send, or a user-owned draft under an explicit editorial review, including review comments, replies, and internal technical reports.
---
# Grounded Writing
## Core principle
- Make the reasoning visible at the scale the artifact supports. Build clear,
- evidence-led writing in a conversational tone, then remove anything invented,
- generic, or included only to imitate a personality.
+ Use Chris Banes's writing as the sole style model. Make the reasoning visible
+ at the scale the artifact supports. Preserve the user's meaning and evidence; remove anything invented, generic, or included
+ only to imitate a personality.
## Procedure
- 1. Confirm that the text is for the user to publish or send, or that the user
- explicitly requested an editorial review of their own draft. Apply this
- style at any length for publication or sending, including one-sentence
- review comments and replies. For an internal report review, apply the truth
- and material-edit checks without imposing public-documentation style. Do
- not apply the skill to an ordinary assistant reply, quoted source text, or
- prose attributed to someone else.
- 2. Read [the style profile](references/style-profile.md) before drafting or
- revising.
- 3. Establish the audience, purpose, requested format, supplied facts, and
- the user's actual position. Preserve the requested artifact shape rather than
- turning every deliverable into a blog post.
- 4. In public developer documentation, explain the observable difference between
- settings and the practical trade-off in supported terms: what each gains and
- gives up, and when to choose each setting. For a publication review, name
- these as separate checks even when the draft lacks evidence to fill them in.
- In a review, explicitly recommend removing each implementation mechanic
- present in the draft that has no established reader-facing significance;
- merely identifying it as a mechanic leaves the edit ambiguous.
- If the draft lacks evidence for that choice,
- name the missing information instead of inferring it. Remove implementation,
- test, or diagnostic mechanics such as sampling thresholds, CPU masks, and
- interpolation details. Retain an observable transition or associated timing
- only when supplied or verified evidence shows it is part of the public
- contract or materially informs how to use or choose the setting. If a draft
- says one setting returns to another, preserve that observable transition
- conditionally while checking whether its timing is a public contract. Say
- that it returns to the other setting without carrying over a “cooldown” term
- or numeric delay unless that timing is verified as reader-facing behavior.
- Do not remove the return behavior merely because its implementation timing
- is unverified. Technical specificity alone does not establish public relevance.
- If relevance could
- change the recommendation but is unknown, flag it for verification rather
- than treating it as settled behavior. Describe retained effects in outcome
- terms and omit their implementation mechanics. Include a mechanic only when
- it is required for correct API use, necessary to distinguish a reader-facing
- setting choice, or explicitly requested. Do not ask to expand internal
- mechanics as a way to fill a public-documentation gap. Before drafting or
- revising public developer documentation, identify its public contracts and
- guarantees shared across alternatives, including compatibility expectations,
- and check that supported guarantees remain explicit in the result. If the
- source leaves a contract uncertain, verify it when research is in scope or
- flag the gap rather than silently dropping or inventing it. Retain the
- context needed to interpret claims. This boundary does not apply to internal
- design documents or technical reports.
- 5. Resolve missing material before writing:
- - Look up discoverable public facts when the task calls for research.
- - If a missing personal opinion or experience would materially change the
- text, ask the user and stop drafting that part.
- - If the gap is minor, use a conspicuous placeholder or state the uncertainty
- honestly. Never invent a first-person claim, result, preference, or memory.
- 6. Choose the register from the style profile. Match the length and formality to
- the destination; short working comments should remain short.
- 7. Shape the reasoning before polishing sentences. Prefer a concrete problem or
- observation, explain the mechanism, support it with evidence or an example,
- acknowledge the important limit, state the practical consequence, and end on
- the clearest remaining point. Omit any stage the artifact does not need. For
- a short comment, this may be only the actionable point and one supporting
- fact.
- 8. Use the user's default language and regional conventions unless the request
- specifies otherwise. Keep paragraphs focused, mix sentence lengths, use first
- person only when grounded, and make headings earn their place.
- 9. Edit once for style and once for truth. Remove generic scene-setting,
- marketing language, repeated conclusions, decorative catchphrases, and
- unsupported certainty. Treat the headline and opening claim as substantive:
- remove or qualify promotional framing that the supplied evidence does not
- directly support.
- 10. For a review that permits edits only for material clarity or truth problems,
- identify the exact claim that is false or the specific misreading that would
- prevent the document's intended use before touching the file. If neither is
- present, leave an adequate draft unchanged. Rewording an already usable
- instruction to make it more explicit is optional polish, not a material
- clarity fix. Do not turn an internal report into a rerun protocol: missing
- identifiers or reproducibility details justify an edit only when a stated
- claim or action depends on them. Do not add a placeholder for an unverified
- detail unless it blocks the draft's intended use. Explain the material facts,
- mechanism, and qualification that make a no-change result appropriate; a
- bare “no edit needed” does not show that the checks
- were completed.
+ 1. Establish scope and authority. Apply this skill to text the user will publish
+ or send, at any length, or to an explicitly requested editorial review of
+ their own draft. Identify whether the task permits drafting, editing, or
+ recommendations only. Preserve the audience, purpose, and requested format.
+ Exclude ordinary assistant replies, quoted source text, and prose attributed
+ to someone else. For internal report reviews, apply truth and material-edit
+ checks without imposing public-documentation style.
+ 2. Establish the evidence and the user's actual position. Never invent personal
+ opinions, experiences, results, preferences, memories, or certainty. Research
+ discoverable public facts when research is in scope. If a missing personal
+ position would materially change the text, ask and pause that part. Otherwise
+ qualify uncertainty or mark a necessary gap conspicuously; do not add
+ placeholders for details that do not affect the artifact's intended use.
+ 3. Select detail for the reader. When public developer documentation compares
+ options, check the observable difference, practical trade-off, and when to
+ choose each separately. Preserve supported public contracts, shared guarantees (including
+ compatibility), meaningful limitations, and context needed to interpret claims.
+ Include implementation mechanics only when required for correct API use,
+ necessary to distinguish a reader-facing choice, or explicitly requested.
+ In reviews, explicitly recommend removing each irrelevant mechanic and name
+ missing decision information rather than inventing it or asking for more
+ internals. Distinguish behavior from implementation: preserve a supported
+ return to another setting even if its timing is unverified; omit the internal
+ timing term and delay unless their public or decision relevance is established.
+ Verify uncertain contracts or relevance when research is in scope; otherwise
+ flag material gaps rather than silently dropping or inventing behavior.
+ Internal reports and design documents may need
+ implementation and diagnostic detail; retain it for their intended use.
+ 4. Read [the style profile](references/style-profile.md) and shape the argument
+ before polishing. Use only the reasoning the artifact needs: a concrete
+ observation, explanation, evidence, relevant limit, and practical consequence.
+ A short reply may need just the actionable point and one supporting fact.
+ 5. Review once for truth and once for style, including the headline and opening
+ claim. Remove or qualify promotional framing and unsupported certainty.
+ For material-only edits, identify the false claim or specific misreading that
+ would prevent the intended use before changing anything. Optional polish is
+ not a material fix. Add reproducibility details only when a stated claim or
+ action depends on them; an internal report need not become a rerun protocol.
+ Leave an adequate draft unchanged and briefly explain the relevant evidence,
+ mechanism, or qualification that supports that conclusion.
+ 6. Deliver the authorized result: write the requested text for a drafting task,
+ apply fixes for an editing task, or give concrete recommendations for a
+ review-only task. Drafting in the response does not authorize file edits.
+ Resolve failed checks below within that boundary. If resolution needs an unknown personal position, ask rather
+ than smoothing over the gap.
## Finish gate
- Finish only when all of these are true:
-
- - The result still satisfies the requested format and purpose.
- - For reader-facing setting documentation, a developer can tell what changes,
- what each setting gains and gives up, when to choose each, the public
- contract, including supported guarantees shared across options, and the
- meaningful limitation. Include transitions or timing only when evidence
- establishes their public or decision relevance; otherwise omit them with the
- implementation detail or flag material uncertainty. Keep implementation
- mechanics out unless they are required for correct API use, necessary to
- distinguish the setting choice, or explicitly requested. In a review, ask
- separately for the visible difference, the practical trade-off, and when to
- choose each setting; a request for a trade-off alone does not cover the
- visible difference. Explicitly recommend removing unsupported mechanics
- present in the draft.
- - Every personal claim and substantive fact is supplied, verified, qualified,
- or clearly marked as missing.
- - The argument is concrete enough to follow without promotional filler.
- - Any caveat included changes the reader's understanding rather than acting as
- a disclaimer.
- - Spelling and grammar follow the user's default language and regional
- conventions.
- - The ending lands once and does not recap the whole piece.
- - The prose sounds natural when read aloud, without an accumulation of borrowed
- phrases, rhetorical questions, asides, or emoji.
+ Finish when the authorized draft, edit, or review:
- If a check fails, revise the draft. If the failure depends on an unknown personal
- position, ask the user rather than smoothing over the gap.
+ - Preserves the requested purpose, format, and material-edit boundary.
+ - Grounds every personal claim and substantive fact in supplied or verified
+ evidence, honest qualification, or a clearly identified necessary gap.
+ - Meets the reader-detail checks in step 3, retaining supported behavior and
+ guarantees without irrelevant mechanics.
+ - Uses the appropriate register and language, with concrete reasoning, useful
+ caveats, and no promotional filler or repeated conclusion.