/ase-docs-proofread

name: ase-docs-proofread
argument-hint: "[--help|-h] [--auto|-a] <docs-reference>"
description: >
    Analyze the documents for spelling, punctuation, or grammar errors.
    Use when the user wants to "proofread" or "spellcheck" 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-proofread"> Analyze documents for spelling, punctuation, or grammar errors </purpose>

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

<objective> *Proofread* the documents of `<getopt-arguments/>` for problems in their *spelling*, *punctuation*, or *grammar* and propose corrections. </objective>

<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/> **PROOFREAD**: *suppressed* (`project.boxing` is `black`) </template>

</if>

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

<template> <ase-tpl-bullet-secondary/> **PROOFREADING 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:       "Proofread Investigation (<batch-index/>/<batch-count/>)",
            subagent_type:     "ase:ase-docs-proofread",
            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/> **PROOFREADING SUMMARY**:

| *Proofread Type* | *Proofread Result* | | ---------------- | ----------------------- | | **SPELLING**: | **<n/>** problems found | | **PUNCTUATION**: | **<m/>** problems found | | **GRAMMAR**: | **<k/>** problems found |

</template>

Hints:

• <n/> is the number of problems with `type` equal to `SPELLING` in <problems/>
• <m/> is the number of problems with `type` equal to `PUNCTUATION` in <problems/>
• <k/> is the number of problems with `type` equal to `GRAMMAR` in <problems/>

</step>

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

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-proofread", 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