/ase-docs-refine

name: ase-docs-refine
argument-hint: "[--help|-h] [--auto|-a] <docs-reference>"
description: >
    Refine the sentence structure and style of the documents: shorten long sentences, replace
    cumbersome nominal constructions with verbs, make enumerations parallel, strike filler words and
    redundancy, fix awkward transitions, and adjust voice, while content, numbers, and technical terms
    stay exactly as they are. Use when the user wants to "refine", "tighten", or "polish" the wording
    of a document.
user-invocable: true
disable-model-invocation: false
effort: high

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-dialog.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

<purpose name="ase-docs-refine"> Refine the sentence structure and style of documents </purpose>

<expand name="getopt" arg1="ase-docs-refine" arg2="--auto|-a"> $ARGUMENTS </expand>

<objective> *Refine* the documents of `<getopt-arguments/>` in their *sentence structure*, *nominal style*, *parallelism*, *filler and redundancy*, *transitions*, and *voice* and propose light rewritings: make long sentences shorter, replace cumbersome nominal constructions with verbs, bring enumerations into one grammatical shape, and strike filler words. *Content, numbers, and technical terms stay exactly as they are.* </objective>

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

This skill performs *light rewriting* of awkward or unclear sentences, *without reshaping the argument*. Every proposed change *MUST* preserve the statement of the original text *exactly*: same facts, same numbers, same technical terms, same qualifiers, same negations, same order of the argument -- only the *wording* changes. A rewriting which shifts the meaning even slightly is *not* a refinement and is *never* applied.

The rewriting stays *within* a sentence. Dropping a whole sentence, paragraph, example, or list item for the sake of brevity is *length reduction*, not refinement, and belongs to the `ase-docs-shorten` skill.

<flow>

1. <step id="STEP 1: Investigation">

<if condition="<ase-project-boxing/> is equal `black`">

The project source artifacts are classified as a *black box*, so the user does *not* want them inspected or their problems surfaced. *Skip* the entire investigation and reporting: do *not* invoke any `Glob` or `Agent` tool and do *not* read any document, only output the following <template/> and then *SKIP* the remaining steps STEP 2 and STEP 3:

<template> <ase-tpl-bullet-normal/> **REFINE**: *suppressed* (`project.boxing` is `black`) </template>

</if>

First, use the following <template/> to give a hint on this step:

<template> <ase-tpl-bullet-secondary/> **REFINEMENT INVESTIGATION** </template>

Dispatch the investigation to *sub-agents* via the `Agent` tool so that *no* investigation details leak into the user-visible transcript. The sub-agents perform the silent reading and checking; only their final structured return values are consumed here.

For this, first *silently* resolve `<getopt-arguments/>` to the list <documents/> of individual document files, expanding any directory or wildcard references with the `Glob` tool. Then partition <documents/>, preserving order, into at most *eight* batches of roughly equal size (a single document yields a single batch), and invoke the following tool once per batch, emitting *all* invocations *in one single message* so they run in *parallel*:

        Agent(
            description:       "Refine Investigation (<batch-index/>/<batch-count/>)",
            subagent_type:     "ase:ase-docs-refine",
            prompt:            <batch/>,
            run_in_background: false
        )

Here <batch/> is the space-separated list of the document file paths of the corresponding batch, <batch-index/> is the 1-based index of that batch, and <batch-count/> is the total number of batches, so that each parallel invocation is distinguishable in the progress display.

Parse the result message of each `Agent` tool invocation as a JSON array, concatenate all those arrays, sort the combined list by `file` and then numerically by `line`, and set <problems/> to that list.

You *MUST* *NOT* output anything at all in this STEP 1 beyond the above hint template and the `Glob` and `Agent` tool invocations. </step>

2. <step id="STEP 2: Summary">

Use the following <template/> to give a summary of the detected problems in <problems/>:

<template> <ase-tpl-bullet-secondary/> **REFINEMENT SUMMARY**:

| *Refinement Type* | *Refinement Result* | | ------------------- | ----------------------- | | **STRUCTURE**: | **<s/>** problems found | | **NOMINALIZATION**: | **<n/>** problems found | | **PARALLELISM**: | **<p/>** problems found | | **FILLER**: | **<f/>** problems found | | **TRANSITION**: | **<t/>** problems found | | **VOICE**: | **<v/>** problems found |

</template>

Hints:

• <s/> is the number of problems with `type` equal to `STRUCTURE` in <problems/>
• <n/> is the number of problems with `type` equal to `NOMINALIZATION` in <problems/>
• <p/> is the number of problems with `type` equal to `PARALLELISM` in <problems/>
• <f/> is the number of problems with `type` equal to `FILLER` in <problems/>
• <t/> is the number of problems with `type` equal to `TRANSITION` in <problems/>
• <v/> is the number of problems with `type` equal to `VOICE` in <problems/>

</step>

3. <step id="STEP 3: Refinement">

1. *Mark this skill as the active edit-capable skill* so that the ASE `pre-tool-use` hook auto-approves the subsequent `Edit` invocations on *any* invocation path (slash command *or* `Sk