ase-docs-refine

@${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 Skill tool). Call the ase_config_set(key: "agent.skill", val: "ase-docs-refine", scope: "session:<ase-session-id/>") tool from the ase MCP server. Do not output anything in this substep.

      Critical safety invariant: the marker set here grants Edit auto-approval and MUST be cleared again (substep 3 below) before this skill yields control, regardless of how the iteration in substep 2 ends - whether it completes normally, is aborted early (e.g. an Edit failure, an unparseable value, or any other unexpected condition), or is otherwise interrupted. If you ever stop or bail out of substep 2 early, you MUST still perform substep 3 first. Never leave this marker active for a later, unrelated Edit.

   2. Set <total/> to the number of problems in <problems/> and <index/> to 0. Then iterate over all problems:

      <for items="<problems/>">

      1. Increment <index/> by one (the 1-based position of the current <item/> within <problems/>). Set <type/> to the type field of <item/>. Set <file/> to the file field of <item/>. Set <line/> to the line field of <item/>. Set <description/> to the description field of <item/>. Set <context-before/> to the context_before field of <item/>. Set <old-text/> to the old_text field of <item/>. Set <new-text/> to the new_text field of <item/>. Set <context-after/> to the context_after field of <item/>.

         Then verify the Ground Rule for this <item/>: compare <new-text/> against <old-text/> and drop the <item/> entirely -- continuing with the next <item/> without any output -- whenever the rewriting shifts the meaning even slightly, i.e., drops, adds, or alters a fact, a number, a technical term, a qualifier, a negation, or a condition.

         Then normalize the change to its minimal form, so that the proposed diff shows exactly the lines the later Edit will actually change: while the first line of <old-text/> is identical to the first line of <new-text/>, move that line from both to the end of <context-before/> and increment <line/> by one; likewise, while the last line of <old-text/> is identical to the last line of <new-text/>, move that line from both to the front of <context-after/>. Finally, trim <context-before/> to its last two lines and <context-after/> to its first two lines.

         Then, unless <ase-project-boxing/> is equal grey (where the full unified diff is suppressed and no context lines are rendered at all), silently read the current content of <file/> with the Read tool - reusing the content read for the same <file/> earlier in this iteration, unless an Edit was applied to it in between - and set <file-lines/> to its lines, stripped of the line-number prefixes the tool adds. Set <file-lines/> to empty if the file cannot be read.

         Whenever <file-lines/> is non-empty, re-derive both context parts from it, overriding the sub-agent supplied values, so the rendered diff shows real context even when a sub-agent supplied none: set <context-before/> to the up to two lines of <file-lines/> directly before line <line/> (empty if <line/> is 1) and <context-after/> to the up to two lines of <file-lines/> starting at line (<line/> + <n/>), where <n/> is the number of lines in <old-text/> (empty if that line is beyond the end of the document). Keep the sub-agent supplied values only when <file-lines/> is empty.

      2. Report the problem with the following <template/>:

         <template> <ase-tpl-bullet-signal/> [<index/>/<total/>]: **<type/> PROBLEM**: `<file/>`:<line/>: <description/> </template>
      3. <if condition="<getopt-option-auto/> is not equal `true` and <ase-project-boxing/> is equal `grey`">

         The project source artifacts are classified as a grey box, so the user does not want the full artifact internals surfaced: suppress the full unified diff and instead show only a condensed one-line representation. Determine <old-snippet/> as the single-line collapse of <old-text/> (join its lines with ⏎, or ∅ when <old-text/> is empty for a pure insertion) and <new-snippet/> as the same collapse of <new-text/> (or ∅ when empty for a pure deletion). Then report the refinement with the following <template/>:

         <template>

         <ase-tpl-bullet-normal/> <type/> REFINEMENT: <old-snippet/> → <new-snippet/>

         </template> </if> <elseif condition="<getopt-option-auto/> is not equal `true`">

         Determine the hunk body as an ordered list of lines, each carrying a one-character prefix ( for context, - for old-side, + for new-side). Build it by concatenating, in order and skipping any part that is empty:

         • one -prefixed line for each line of <context-before/> (if non-empty),
         • one --prefixed line for each line of <old-text/> (if non-empty; split <old-text/> on newlines),
         • one +-prefixed line for each line of <new-text/> (if non-empty; split <new-text/> on newlines),
         • one -prefixed line for each line of <context-after/> (if non-empty).

         Set <hunk-body/> to those prefixed lines joined by newlines.

         Set <old-count/> to the number of old-side hunk lines, i.e., the combined line count of <context-before/>, <old-text/>, and <context-after/> (each empty part counts as 0). Set <new-count/> to the number of new-side hunk lines, i.e., the combined line count of <context-before/>, <new-text/>, and <context-after/> (each empty part counts as 0).

         Set <old-start/> to the 1-based line number of the first old-side hunk line: if <context-before/> is non-empty, that is the line of its first context line, i.e., <line/> minus the number of lines in <context-before/>; otherwise it is <line/> itself (the first line of <old-text/>). For a hunk that only inserts new lines (empty <old-text/> and empty context), set it to the line before which the insertion happens, clamped to a minimum of 0, so a top-of-file insertion yields @@ -0,0 ... @@. Set <new-start/> to the same value as <old-start/>, but clamped to a minimum of 1 whenever <new-count/> is greater than 0 (the refined side then has a real first line).

         Render the proposed refinement as a unified diff with up to two lines of context in a fenced block based on the following <template/>, emitting <hunk-body/> verbatim (one already-prefixed line per line, with no extra blank or space-only lines):

         <template>

         <ase-tpl-bullet-normal/> <type/> REFINEMENT:

         --- <file/> (original)
         +++ <file/> (refined)
         @@ -<old-start/>,<old-count/> +<new-start/>,<new-count/> @@
         <hunk-body/>
         

         </template> </elseif>
      4. <if condition="<getopt-option-auto/> is not equal `true`">

         In the following, you MUST NOT use your built-in <user-dialog-tool/> tool! Instead, you MUST just show a custom dialog according to the expanded custom-dialog definition. You MUST closely follow this definition:

         <expand name="custom-dialog" arg1="--other"> REFINEMENT: How would you like to proceed with this proposed refinement? ACCEPT: Apply this proposed refinement. REJECT: Skip this proposed refinement. </expand> </if> <else>

         Set <result>ACCEPT</result>.

         </else>

      5. Check <result/> and dispatch accordingly:

         • <if condition="<result/> is 'ACCEPT'">

           Invoke the Edit tool to apply the change by replacing <old-text/> with <new-text/> at <file/>:<line/>. The operation will be auto-approved by the ASE pre-tool-use hook (which tracks the active skill), so no interactive permission prompt will appear. Then continue with the next <item/>.

           </if>
         • <if condition="<result/> starts with 'OTHER'">

           Generate a new proposal for the same <item/>, incorporating the user's free-text hint from <result/> after the "OTHER:" prefix. Reassign <description/>, <old-text/>, and <new-text/> to reflect this refined proposal (<old-text/> stays anchored to the existing text at <file/>:<line/>; <new-text/> and <description/> carry the refinement) so the subsequent rendering and any Edit use the new proposal rather than the original. Then re-apply the minimal-form normalization of substep 1 to the refined <old-text/> and <new-text/> (so the re-rendered diff again shows exactly the changed lines) and go back to substep 2 of this for-iteration. There is no cap on refinement rounds - keep refining until the user picks ACCEPT or REJECT.

           </if>

         • <if condition=" <result/> is 'REJECT' or <result/> is 'CANCEL' or <result/> starts with 'ERROR' ">

           Skip this <item/> without any Edit call and continue with the next <item/>.

           </if>
      </for>

   3. Clear the active edit-capable skill marker now that all Edit invocations are done, so a later unrelated Edit is not auto-approved. Call the ase_config_delete(key: "agent.skill", scope: "session:<ase-session-id/>") tool from the ase MCP server. Do not output anything in this substep.

   4. You MUST NOT output any further additional explanations or summaries at the end of this skill processing, except for the following final <template/>:

      <template> <ase-tpl-bullet-secondary/> **REFINE FINISHED** </template>

   5. Finally, give the closing hint by expanding the following (which, depending on the configured <ase-guidance-level/>, may expand into nothing and hence emit no output at all):

      <if condition="<getopt-option-auto/> is not equal `true`"> <ase-tpl-hint level="verbose"> Use `/ase-docs-refine --auto` to apply all refinements unattended. </ase-tpl-hint> </if>
   </step>

</flow>