/ase-docs-shorten

name: ase-docs-shorten
argument-hint: "[--help|-h] [--auto|-a] (--chars|-c <N> | --words|-w <N>) <docs-reference>"
description: >
    Shorten a document toward a target length, given as either `--chars <N>` or `--words <N>`: first
    tighten the sentences, then drop low-value content, then compress the remaining content into
    shorter expressions -- each stage entered only while the target is still not met. Use when the
    user wants to "shorten", "cut down", or "reduce the length 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-shorten"> Shorten a Document to a Target Length </purpose>

<expand name="getopt" arg1="ase-docs-shorten" arg2="--auto|-a --chars|-c=0 --words|-w=0"> $ARGUMENTS </expand>

<objective> *Shorten* the document of `<getopt-arguments/>` until it reaches the requested *target length* by running three *stages* in order -- tighten the sentences, drop low-value content, compress the remaining content into shorter expressions -- and entering each stage *only* while the target is still not met. </objective>

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

This skill *removes* text, so unlike `ase-docs-refine` it *MAY* lose content. It still *MUST* *NOT* corrupt whatever survives: every fact, number, technical term, qualifier, and negation which *survives* into the shortened text stays *exactly* as it was, no content is invented, the order of the surviving argument is kept, and fenced code blocks, inline code spans, link targets, Markdown frontmatter, and the heading structure are never touched.

The skill also *MUST* *NOT* shorten *beyond* the target: it stops at the first change which reaches the target, so a document is never cut more than the user asked for.

<flow>

1. <step id="STEP 1: Resolve Target and Document">

1. Determine the *target length* from the two mutually exclusive options. Set <chars/> to <getopt-option-chars/> and <words/> to <getopt-option-words/>, treating a *non-numeric* or *negative* value as `0`. Then dispatch:

• <if condition="<chars/> is `0` and <words/> is `0`">

Only output the following <template/> and then *IMMEDIATELY* *STOP* all further skill processing:

<template> ⧉ **ASE**: ✪ skill: **ase-docs-shorten**, ▶ ERROR: a target length is required -- pass either `--chars <N>` or `--words <N>` </template>

</if>

• <if condition="<chars/> is not `0` and <words/> is not `0`">

Only output the following <template/> and then *IMMEDIATELY* *STOP* all further skill processing:

<template> ⧉ **ASE**: ✪ skill: **ase-docs-shorten**, ▶ ERROR: `--chars` and `--words` are mutually exclusive -- pass only one of them </template>

</if>

• <if condition="<chars/> is not `0`">

Set <unit>chars</unit> and <target><chars/></target>. </if> <else> Set <unit>words</unit> and <target><words/></target>. </else>

Do not output anything else in this substep.

2. *Silently* resolve `<getopt-arguments/>` to the list <documents/> of individual document files, expanding any directory or wildcard reference with the `Glob` tool. Then dispatch:

• <if condition="<documents/> is empty">

Only output the following <template/> and then *IMMEDIATELY* *STOP* all further skill processing:

<template> ⧉ **ASE**: ✪ skill: **ase-docs-shorten**, ▶ ERROR: no document to shorten </template>

</if>

• <if condition="<documents/> carries more than one document">

A target length applies to *one* document, so a reference which expands to several documents is *ambiguous*: it is unclear whether the target bounds each document or their sum. Set <count/> to the number of documents, then only output the following <template/> and *IMMEDIATELY* *STOP* all further skill processing:

<template> ⧉ **ASE**: ✪ skill: **ase-docs-shorten**, ▶ ERROR: **<count/>** documents referenced -- a target length applies to exactly one document </template>

</if>

Set <file/> to the single document of <documents/>.

3. Do not output anything else in this STEP 1.

</step>

2. <step id="STEP 2: 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 `Agent` tool and do *not* read any document, only output the following <template/> and then *SKIP* the remaining steps STEP 3, STEP 4, and STEP 5:

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

</if>

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

<template> <ase-tpl-bullet-secondary/> **SHORTENING INVESTIGATION**: `<file/>` → **<target/>** <unit/> </template>

Dispatch the investigation to a *sub-agent* via the `Agent` tool so that *no* investigation details leak into the user-visible transcript. The sub-agent performs the silent reading, measuring, and shortening; only its final structured return value is consumed here. As a target length applies to exactly *one* document, exactly *one* sub-agent is invoked, which keeps the length budget coherent:

        Agent(
            description:       "Shorten Investigation",