@rse/ase 0.9.65 → 0.9.67

package/plugin/skills/ase-docs-refine/SKILL.md

@@ -0,0 +1,396 @@
+---
+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*:
+
+    ```text
+        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**:
+
+            ```diff
+            --- <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>

package/plugin/skills/ase-docs-refine/help.md

@@ -0,0 +1,104 @@
+
+##  NAME
+
+`ase-docs-refine` - Refine Document Wording
+
+##  SYNOPSIS
+
+`ase-docs-refine`
+    [`--help`|`-h`]
+    [`--auto`|`-a`]
+    *docs-reference*
+
+##  DESCRIPTION
+
+The `ase-docs-refine` skill performs a *light rewriting* of awkward or
+unclear sentences in the referenced documents, *without reshaping the
+argument*: restructuring sentences for rhythm and clarity, making
+enumerations parallel, cutting filler and redundancy, fixing awkward
+transitions, and adjusting voice. *Content, numbers, and technical
+terms stay exactly as they are.* The investigation is dispatched to a
+sub-agent (`ase:ase-docs-refine`) so that scanning details do not leak
+into the user-visible transcript.
+
+The checked refinement types are:
+
+1.  *Structure*: overlong, convoluted, or awkwardly built sentences,
+    split or restructured for rhythm and clarity.
+
+2.  *Nominalization*: cumbersome nominal constructions, replaced with
+    plain verbs.
+
+3.  *Parallelism*: non-parallel enumerations, brought into one
+    grammatical shape - a 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.
+
+4.  *Filler*: filler words, empty intensifiers, and redundant
+    restatements, struck.
+
+5.  *Transition*: abrupt or misleading transitions between sentences or
+    paragraphs, smoothed. An existing transition is only smoothed or
+    removed - a connective is *never* inserted where the original
+    asserted no such relation, as that would add a logical claim.
+
+6.  *Voice*: needless passive voice turned active, needless hedging
+    struck, and shifts in grammatical person or mood aligned with the
+    rest of the document.
+
+The rewriting always 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
+[`ase-docs-shorten`](../ase-docs-shorten/help.md). The recommended order
+over one document is `ase-docs-shorten` first (cut the bulk), then
+`ase-docs-refine` (polish what survives), then `ase-docs-proofread`
+(final correctness pass), so no polishing effort is spent on text which
+is later dropped.
+
+For each detected problem, the skill renders a unified-diff
+*REFINEMENT* preview and either asks the user to `ACCEPT` or `REJECT`
+the proposed refinement interactively (or refine it via a free-text
+hint, which re-proposes the refinement without limit) or - with
+`--auto` - applies all refinements automatically. A proposal which
+shifts the meaning even slightly - a lost negation, a changed
+qualifier, a renamed technical term - is dropped instead of applied.
+
+##  OPTIONS
+
+-   `--auto`|`-a`:
+    Automatically apply every proposed refinement without asking the
+    user via the interactive dialog.
+
+##  ARGUMENTS
+
+-   *docs-reference*:
+    A file, directory, or other reference to the documents to
+    refine.
+
+##  SCENARIOS
+
+-   You want long, convoluted sentences broken into readable ones
+-   You want nominal style like "perform a validation of" turned into verbs
+-   You want a bullet list of mixed noun phrases and sentences made parallel
+-   You want filler words and redundant restatements struck
+-   You want abrupt transitions between paragraphs smoothed
+-   You want needless passive voice or hedging adjusted
+-   You want the wording polished without touching facts or figures
+
+##  EXAMPLES
+
+Refine a single document interactively:
+
+```text
+❯ /ase-docs-refine README.md
+```
+
+Refine an entire documentation directory automatically:
+
+```text
+❯ /ase-docs-refine --auto docs/
+```
+
+##  SEE ALSO
+
+[`ase-docs-shorten`](../ase-docs-shorten/help.md), [`ase-docs-proofread`](../ase-docs-proofread/help.md), [`ase-docs-distill`](../ase-docs-distill/help.md).