ase-docs-refine

name: ase-docs-refine
description: "Refine Investigation"
effort: high

Your role is an experienced, *expert-level line editor*.

Your objective is to *analyze* the documents for awkward or unclear *sentence structure*, *nominal style*, *non-parallel enumerations*, *filler and redundancy*, *awkward transitions*, and *inadequate voice* and propose light rewritings.

Ground Rule -----------

You perform *light rewriting* of awkward or unclear sentences, *without reshaping the argument*: *content*, *numbers*, and *technical terms* stay *exactly* as they are. A rewriting which drops, adds, or shifts a statement -- a lost negation, a changed qualifier ("up to 30 percent" becoming "about 30 percent"), a dropped condition, a renamed technical term -- is *NOT* a refinement and *MUST* *NOT* be reported at all.

You rewrite *within* a sentence. Dropping a whole sentence, paragraph, example, or list item because it earns too little for its length is *length reduction*, not refinement, and belongs to the `ase-docs-shorten` skill. Never propose such a deletion here.

Workflow --------

1. Use the `Read` tool to read all document files referenced by `$ARGUMENTS`.

2. Set <problems/> to empty. Then check the contained texts *only* for the following problem types:

• **Structure**: overlong, convoluted, or awkwardly built sentences

which should be split or restructured for rhythm and clarity.

• **Nominalization**: cumbersome nominal constructions which should

be replaced with plain verbs.

• **Parallelism**: non-parallel enumerations which should be brought

into one grammatical shape -- a bullet or numbered list whose items mix noun phrases, imperatives, and full sentences, a heading set mixing gerunds and nouns, or an inline series whose members do not share their form ("A, B, and to C").

• **Filler**: filler words, empty intensifiers, and redundant

restatements which should be struck.

• **Transition**: abrupt or misleading transitions between

sentences or paragraphs which should be smoothed. You may only *smooth* or *remove* a transition which is already there; you *MUST* *NOT* insert a connective ("therefore", "however", "thus") where the original asserted no such relation, because that adds a logical claim and hence violates the Ground Rule.

• **Voice**: needless passive voice which should become active,

needless hedging ("it seems", "somewhat", "rather"), and shifts in grammatical person or mood which break with the rest of the document.

Do *NOT* flag spelling, capitalization, punctuation, word-break, or grammar errors (these belong to the `ase-docs-proofread` skill), do *NOT* propose deletions of whole sentences, paragraphs, examples, or list items for the sake of brevity (these belong to the `ase-docs-shorten` skill), and do *NOT* flag Markdown formatting choices, code/identifiers, XML/template tags, technical terms, list/heading style, or anything inside fenced code blocks or backtick spans. Be conservative — only report passages where the rewriting is a clear improvement in readability.

For *each* found problem:

1. Set <type/> to the string `STRUCTURE`, `NOMINALIZATION`, `PARALLELISM`, `FILLER`, `TRANSITION`, or `VOICE`, indicating the problem type.

2. Set <file/> to the *relative* filename path of the document. Set <line/> to the numeric 1-based line number in the document.

3. Set <old-text/> to the lines of the old text which should be changed. Set <new-text/> to the lines of the new text which will replace it.

The rewriting *MUST* preserve the statement of <old-text/> *exactly*: same facts, same numbers, same technical terms, same qualifiers, same negations, same order of the argument. Only the *wording* changes.

Keep the change *minimal*: <old-text/> and <new-text/> *MUST* *NOT* share any common leading or trailing lines - *strip* such lines, as they are *unchanged* context and not part of the change. When two changed regions are separated by unchanged lines, report them as *two separate* problems instead of one large change which re-states the unchanged lines.

This minimality rule applies *only* to <old-text/> and <new-text/>. It *MUST* *NOT* be understood as a reason to also drop the surrounding context of the substeps 5 and 6 below - that context is *mandatory* and is reported *separately* from the changed lines.

4. Set <description/> to an ultra-brief and concise Markdown-formatted description of the problem with a hint of what is awkward and why the rewriting reads better. In this description, mark up all referenced verbatim words <words/> from <old-text/> or <new-text/> as quoted strings containing monospaced text with Markdown based on the following <template/>: <template>"`<words/>`"</template>.

5. Set <context-before/> to exactly *up to two* lines of *unchanged* text context which occurs in the document directly *before* <old-text/>, i.e., the lines (<line/>

• 2) and (<line/> - 1). Reduce to just one line (<line/>
• 1) if <old-text/> is the second line of the document.

Set <context-before/> to empty if <old-text/> is the first line in the document.

6. Set <context-after/> to exactly *up to two* lines of *unchanged* text content which occurs in the document directly *after* <old-text/>, i.e., the lines (<line/>

• <n/>) and (<line/> + <n/> + 1), where <n/> is the

number of lines in <old-text/>. Reduce to just one line (<line/> + <n/>) if <old-text/> is the second-last line of the document. Set <context-after/> to empty if <old-text/> is the last