--- name: report-clarity description: Audit or revise report prose for reader context, terminology, argument flow, relevance and internal cross-references. Use for deep clarity passes, local wording issues that may recur, or standalone reflections with reader-context gaps. --- # Report clarity Make the report understandable to its intended reader without relying on conversation history or a companion report. Preserve technical meaning and useful concision. Follow the user's review/edit scope. ## Recurring issues Whenever a user or reviewer identifies a complex or systematic issue that plausibly recurs, formulate or refine a contextual pattern and record the example. Apply the pattern across the draft when that broader check is already authorised; otherwise explicitly offer the wider pass alongside addressing the local request. Follow the [recurring-pattern procedure](../report-review/references/recurring-patterns.md) for scope, contextual matching, counterexamples and completion. This applies even when only one instance has been pointed out; a routine isolated typo does not automatically justify a broad audit. ## Contextual pass Read [patterns and counterexamples](references/patterns.md) before a deep pass or when diagnosing a local issue that may reveal a wider pattern. Establish audience, genre, required structure, approved wording, and technical invariants. For a standalone reflection, concepts explained only in the research report still need local context. Inventory the in-scope document, including visual text and appendices. Read paragraphs with their neighbours and visual lead-ins. For every user example, identify the missing relationship or reasoning step, then use the recurring-pattern procedure to determine the scope of analogous checks, including cases whose words differ. Search is a candidate finder, followed by contextual reading. Give each candidate a correction or a reason to retain it. Clear preceding context can justify shorthand; neither all technical terms nor all repeated names need expansion. Protect exact approved spans without exempting neighbouring text. Verify every recorded example after editing and reread the resulting sections as a new reader. ## Substantive fixes before polish Resolve referents, conceptual ordering, factual scope and section purposes first. Keep main-text explanations needed to understand the argument; move lengthy reproducibility detail to an appendix only when it remains useful. Remove incidental history and duplication, while preserving methods, rationale, challenges and limitations required by the brief. Maintain clear distinctions between the central contribution, its implementation, and its demonstrated setting. Name an artefact, its format, and its version in ways that explain their relationship. Retain exact private versions only when readers need them to interpret or reproduce results; otherwise use meaningful configuration descriptions and keep exact identities in project records. Public standards versions remain where technically material. When removing an obsolete table, identifier or repeated explanation, preserve any unique necessary content and update all dependent prose, references and visual labels. ## Editorial sequence Once substantive edits are stable, apply these passes in order, recording actual changes and justified retention. If the user selected additional writing skills, read their current instructions and integrate compatible steps at this stage; never claim an unavailable named skill was run. 1. Clear prose: remove avoidable noun stacks, unnecessary contrasts, filler, repetition and vague actors. Prefer precise verbs and established terminology over decorative synonyms. 2. Authorial voice: preserve the genre, chosen English variety and credible authorship. First person is a style decision governed by actual requirements; do not invent an external operator or reviewer to avoid it. Preserve personal statements unless authorised to revise them. Do not invent experiences or claim to evade AI detection. 3. Academic precision: recheck qualifiers, scope, causal language, tense and responsibility. Completed work, definitions and proposals should remain distinguishable. Formatting and formal vocabulary do not themselves establish rigour. 4. Citation and reference regression: ensure rephrased claims still have appropriate support and useful internal pointers. Use report-evidence for substantive verification when needed. 5. Sceptical final read: check that the introduction, methods, findings, conclusion and abstract tell a consistent story. For reflections, check the link from experience to insight and future practice. Do not mechanically impose a paragraph formula. Outcome-first summaries are valid; problem-before-decision is especially useful when explaining a design transition. Stop rephrasing once the problem is solved. ## Finish Compare before/after for changed numbers, populations, conditions, attribution, uncertainty and code literals. Check logical force too: negation, inclusive bounds, causal versus associative wording, and whether an edit shifts a claim from evaluating benefits to asserting they were achieved. A smoother sentence must preserve these distinctions. Report contextual coverage and unresolved factual questions. If asked to edit a document, use its applicable authoring/build workflow to keep the deliverable current; an extraction-only check does not establish visual quality.