@rse/ase 0.9.2 → 0.9.4

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

@@ -0,0 +1,158 @@
+---
+name: ase-docs-distill
+argument-hint: "[--help|-h] [--top|-t <N>] <document-reference>"
+description: >
+    Distill a provided document into a flat, importance-ranked list
+    of its key points, each with a salience rank, a rationale, and a
+    verbatim line-cited evidence snippet. Use when the user wants to
+    "distill", "summarize the key points", or "extract the essence" of a
+    document or pasted text.
+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-getopt.md
+
+<skill name="ase-docs-distill">
+    Distill Key Points
+</skill>
+
+<expand name="getopt"
+    arg1="ase-docs-distill"
+    arg2="--top|-t=5">
+    $ARGUMENTS
+</expand>
+
+<objective>
+    *Distill* the content `<getopt-arguments/>` into a *flat*,
+    *importance-ranked* list of its *key points* - each point an
+    *atomic* claim carrying a *0-10 salience rank*, a *one-line
+    rationale*, and a *verbatim, line-cited evidence* snippet - keeping
+    at most `<getopt-option-top/>` points.
+</objective>
+
+Procedure
+---------
+
+You *MUST* follow the following numbered items *strictly* *sequentially*!
+You *MUST* not skip any numbered item during processing!
+
+You *MUST* *NOT* output anything in this entire procedure, *except* when
+explicitly requested by this procedure via outputs based on a <template/>!
+
+<flow>
+
+1.  <step id="STEP 1: Resolve Input">
+
+    Resolve the document source from <getopt-arguments/> using
+    *probe-as-file-first* semantics:
+
+    1.  <if condition="<getopt-arguments/> is empty">
+
+        Only output the following <template/> and then *STOP* immediately:
+
+        <template>
+        ⧉ **ASE**: ✪ skill: **ase-docs-distill**, ▶ status: **no document to distill**
+        </template>
+
+        </if>
+
+    2.  Treat the *entire* <getopt-arguments/> as a *file path*. If it
+        resolves to a *readable file*, read that file and capture its
+        content together with its *line numbers* into <source/>, and set
+        <origin/> to the file path.
+
+    3.  <if condition="<getopt-arguments/> does NOT resolve to a readable file">
+
+        Treat <getopt-arguments/> *verbatim* as *pasted text*, capture it
+        into <source/> numbering its lines from *1*, and set <origin/>
+        to empty (so locations are cited as `:Ls-Le`).
+
+        </if>
+
+    4.  <if condition="<source/> is empty">
+
+        Only output the following <template/> and then *STOP* immediately:
+
+        <template>
+        ⧉ **ASE**: ✪ skill: **ase-docs-distill**, ▶ status: **no document to distill**
+        </template>
+
+        </if>
+
+    You *MUST* *NOT* output anything in this STEP 1.
+
+    </step>
+
+2.  <step id="STEP 2: Distill Key Points">
+
+    Read <source/> and distill it into its *key points*.
+
+    1.  Extract the document's *key points*, where each point is *one
+        atomic, self-contained claim, decision, or fact* - *not* a
+        section-level summary that blends several claims.
+
+    2.  For each point, determine:
+
+        -   A <rank/> on a *0-10* salience scale reflecting its
+            *importance-to-the-reader* (impact, centrality, consequence)
+            - *not* its position in the document.
+
+        -   A one-line <rationale/> that justifies *why* the point earns
+            that <rank/>.
+
+        -   A <location/> citing the exact source line range as
+            `<origin/>:Ls-Le` (for a file) or `:Ls-Le` (for pasted text),
+            where `Ls` is the start line and `Le` is the end line.
+
+        -   A *verbatim* <evidence/> snippet, copied exactly from
+            <source/> (but with all newlines replaced with spaces
+            and multiple spaces collapsed into a single space), that
+            *proves* the point. The cited snippet *MUST* prove the
+            point verbatim. If it does not, *re-investigate and re-cite
+            correctly*.
+
+    3.  *Sort* the points by <rank/> from *highest to lowest*. Within the
+        same rank, keep the order of first appearance in <source/>.
+
+    4.  Apply the *top-bound* <getopt-option-top/> as an *upper bound
+        only*: keep at most `min(<getopt-option-top/>, number of salient
+        points)` points and *never pad* the list with filler to reach
+        the bound. If <getopt-option-top/> is *non-numeric* or *less
+        than or equal to 0*, use the default *10* instead.
+
+    You *MUST* *NOT* output anything in this STEP 2.
+
+    </step>
+
+3.  <step id="STEP 3: Report Ranked Points">
+
+    For each distilled point, emit the following <template/>,
+    where <rank/> is its salience rank, <point/> is the atomic claim,
+    <location/> is its line-range citation, <evidence/> is the
+    verbatim proving snippet, and <rationale/> is the one-line
+    salience justification:
+
+    <template>
+
+    <ase-tpl-bullet-normal/> **KEY POINT**: **<point/>**
+
+    ◯ LOCATION:  <location/>
+    ◯ EVIDENCE:  "`<evidence/>`"
+    ◯ RATIONALE: <rationale/>
+    ◯ RANK:      <rank/>/10
+
+    </template>
+
+    In the <location/>, markup the line-range reference as
+    code (with backticks) and prepend it with `▢ `.
+
+    Keep the overall report *concise* and *brief*. Do *not* output any
+    further explanation.
+
+    </step>
+
+</flow>

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

@@ -0,0 +1,76 @@
+
+##  NAME
+
+`ase-docs-distill` - Distill Document Key Points
+
+##  SYNOPSIS
+
+`ase-docs-distill`
+    [`--help`|`-h`]
+    [`--top`|`-t` *N*]
+    *document-reference*
+
+##  DESCRIPTION
+
+The `ase-docs-distill` skill reads a *provided document* and distills it
+into a *flat*, *importance-ranked* list of its *key points*. The
+*docs-reference* is resolved *probe-as-file-first*: if the argument names
+a *readable file* it is read from disk, otherwise the argument is taken
+*verbatim* as *pasted text*. The document is read *silently* - only the
+final ranked list is shown - so even a large document does not flood the
+transcript.
+
+Each emitted point is *one atomic claim, decision, or fact* (not a
+section-level summary) and carries four things: a *0-10 salience rank*
+reflecting its *importance to the reader* (impact and centrality, *not*
+its position in the document), a *one-line rationale* justifying *why* it
+earns that rank, an exact *line-range citation* (`file:Ls-Le`, or `:Ls-Le`
+for pasted text), and a *verbatim evidence* snippet copied from the source
+that *proves* the point. The points are emitted as a *bulleted list* -
+one block per point, each showing its *LOCATION*, *EVIDENCE*,
+*RATIONALE*, and *RANK* - sorted from highest to lowest salience, so the
+ranking is *auditable* rather than an opaque ordering.
+
+The `--top`/`-t` *N* option is a *length dial* that bounds the list to at
+most *N* points (default *10*). It is an *upper bound only*: when the
+document has fewer salient points than *N*, the skill emits only the
+points it found and *never pads* the list with filler; a `0`, negative, or
+non-numeric value falls back to the default *10*.
+
+##  ARGUMENTS
+
+`--top`, `-t` *N*:
+    Bound the ranked list to at most *N* key points (default *10*). The
+    bound is a *cap*, never a *quota* - fewer points are emitted when the
+    document does not contain *N* salient ones, and an invalid or
+    non-positive *N* reverts to the default.
+
+*docs-reference*:
+    The document to distill - either a *path* to a readable file or the
+    *text* itself pasted inline. If it resolves to a readable file the
+    file is read; otherwise it is treated verbatim as pasted text.
+
+##  EXAMPLES
+
+Distill the key points of a document file:
+
+```text
+❯ /ase-docs-distill doc/architecture.md
+```
+
+Distill only the top 5 key points:
+
+```text
+❯ /ase-docs-distill --top 5 doc/architecture.md
+```
+
+Distill a pasted block of text:
+
+```text
+❯ /ase-docs-distill The system shall accept payments in EUR and USD only.
+```
+
+##  SEE ALSO
+
+`ase-meta-search`, `ase-docs-proofread`, `ase-meta-why`.
+

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

@@ -175,7 +175,7 @@ Analyze documents for spelling, punctuation, or grammar errors
                 Generate a *new* proposal for the *same* <item/>,
                 incorporating the user's free-text hint from <result/>
                 after the "OTHER:" prefix, and loop back to substep 2 of
-                this iteration. There is *no* cap on refinement rounds —
+                this iteration. There is *no* cap on refinement rounds -
                 keep refining until the user picks `ACCEPT` or `REJECT`.
 
                 </if>

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

@@ -20,7 +20,7 @@ the user-visible transcript.
 
 For each detected problem, the skill renders a unified-diff
 *CORRECTION* preview and either asks the user to `ACCEPT` or `REJECT`
-the proposed correction interactively or — with `--auto` — applies
+the proposed correction interactively or - with `--auto` - applies
 all corrections automatically.
 
 ##  OPTIONS

package/plugin/skills/ase-meta-brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ase-meta-brainstorm
-argument-hint: "[--help|-h] <topic>"
+argument-hint: "[--help|-h] [--count|-c=12] <topic>"
 description: >
     Collaboratively brainstorm a topic by diverging on ideas, converging
     through clustering and scoring, and distilling a shortlist with
@@ -15,13 +15,20 @@ 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
 
 <skill name="ase-meta-brainstorm">
 Collaboratively Brainstorm a Topic
 </skill>
 
+<expand name="getopt"
+    arg1="ase-meta-brainstorm"
+    arg2="--count|-c=12">
+    $ARGUMENTS
+</expand>
+
 <objective>
-Collaboratively brainstorm the topic <topic>$ARGUMENTS</topic> by first
+Collaboratively brainstorm the topic <topic><getopt-arguments/></topic> by first
 *diverging* into a broad space of candidate ideas, then *converging*
 through clustering and scoring, and finally distilling a *shortlist*
 with a single recommended direction.
@@ -33,8 +40,8 @@ Guiding Tenets
 Honor the following tenets throughout the brainstorming:
 
 -   **No Assumption of Simplicity**:
-    Every topic goes through the full process — a one-line config
-    change as much as a new subsystem — because the simplest-looking
+    Every topic goes through the full process - a one-line config
+    change as much as a new subsystem - because the simplest-looking
     topics often hide the most harmful assumptions.
 
 -   **Explore Intent First**:
@@ -83,9 +90,15 @@ Honor the following tenets throughout the brainstorming:
 
     Before generating any ideas, *explore the project context* (review
     relevant existing files, documentation, and recent changes) and
-    determine the <m/> *essential unknowns* about the topic — the
-    purpose, constraints, scope boundaries, and success criteria that
-    must be pinned down for the brainstorming to be reasonably grounded.
+    determine the <m/> (<m/>=1-3) *essential unknowns* about the topic
+    - the purpose, constraints, scope boundaries, and success criteria
+    that must be pinned down for the brainstorming to be reasonably
+    grounded.
+
+    Notice: you are intentionally constrained to just 1-3 unknowns,
+    as too much upfront intent clarification kills the brainstorming
+    of ideas later. So, you *MUST* reduce the clarifications of the
+    unknowns to the absolute minimum!
 
     For each essential unknown, derive a short 1-3 word facet <facet-M/>
     and a corresponding question <question-M/> whose answer materially
@@ -139,15 +152,16 @@ Honor the following tenets throughout the brainstorming:
     <topic/> within the constraints established by the answers
     <answer-M/>.
 
-    Deliberately pursue *diverse angles* — e.g. the minimal/MVP-first
+    Deliberately pursue *diverse angles* - e.g. the minimal/MVP-first
     angle, the robustness/risk-first angle, the user-experience-first
     angle, the reuse-existing-machinery angle, the coolness angle, and
-    the unconventional/wildcard angle — because variety in origin yields
+    the unconventional/wildcard angle - because variety in origin yields
     variety in outcome.
 
     Do still *not* judge, rank, or prune ideas in this step. Generate
-    ideas until you either reach at least 12 distinct candidate ideas or
-    have clearly exhausted the meaningfully distinct space.
+    ideas until you either reach at least <getopt-option-count/> distinct
+    candidate ideas or have clearly exhausted the meaningfully distinct
+    space.
 
     Store each candidate idea in <idea-N/> with the format
     `**<idea-name-N/>**: <idea-statement-N/>` (where <idea-name-N/> is a
@@ -177,7 +191,7 @@ Honor the following tenets throughout the brainstorming:
         statement of not more than 40 words):
 
         <template>
-        <ase-tpl-bullet-secondary/> **IDEA CLUSTER <C/>/<c/>**: <cluster-C/> — <cluster-summary-C/>,
+        <ase-tpl-bullet-secondary/> **IDEA CLUSTER <C/>/<c/>**: <cluster-C/> - <cluster-summary-C/>,
         **IDEAS**: <N/>, <M/>[, ...]
         </template>
 
@@ -191,7 +205,7 @@ Honor the following tenets throughout the brainstorming:
         3-4 options, sorted by rank from highest to lowest.
 
         For this, draw the shortlist from *distinct* clusters <cluster-C/>
-        wherever possible — prefer a diverse shortlist spanning different
+        wherever possible - prefer a diverse shortlist spanning different
         clusters over several high-ranked variations of the same cluster,
         unless one cluster clearly dominates on rank.
 
@@ -205,9 +219,9 @@ Honor the following tenets throughout the brainstorming:
         <ase-tpl-bullet-normal/> **DISTILLED IDEA <N/>**: <option-N/>
         </template>
 
-    4.  Finally, derive a single *recommended idea* — the highest-ranked
+    4.  Finally, derive a single *recommended idea* - the highest-ranked
         option, or a principled synthesis of the option shortlist that preserves
-        what is strongest in each — store its one-sentence rationale (not
+        what is strongest in each - store its one-sentence rationale (not
         more than 40 words) in <recommendation/>, and output the following
         <template/>:
 

package/plugin/skills/ase-meta-brainstorm/help.md

@@ -7,6 +7,7 @@
 
 `ase-meta-brainstorm`
     [`--help`|`-h`]
+    [`--count`|`-c=12`]
     *topic*
 
 ##  DESCRIPTION
@@ -14,17 +15,17 @@
 The `ase-meta-brainstorm` skill guides a collaborative ideation
 session on a *topic* *before* any implementation begins. It first
 *clarifies intent* by exploring the project context and interviewing
-the user — one grounded, multiple-choice question at a time — about
+the user - one grounded, multiple-choice question at a time - about
 purpose, constraints, scope, and success criteria. It then *diverges*
-into a broad space of candidate ideas pursued from deliberately diverse
-angles (MVP-first, risk-first, UX-first, reuse-first, and wildcard),
-without judging them.
+into a broad space of candidate ideas (at least `--count`, default 12)
+pursued from deliberately diverse angles (MVP-first, risk-first,
+UX-first, reuse-first, and wildcard), without judging them.
 
 Next it *converges* by clustering the ideas into coherent themes,
 pruning speculative or out-of-scope ones via *YAGNI*, and scoring the
 survivors on a 0-10 fit scale (keeping only those ranked 7 or higher).
-Finally it distills a *shortlist* of the top 3-4 directions — drawn from
-distinct clusters wherever possible — and derives a single
+Finally it distills a *shortlist* of the top 3-4 directions - drawn from
+distinct clusters wherever possible - and derives a single
 *RECOMMENDATION*, being either the highest-ranked option or a principled
 synthesis of the shortlist.
 
@@ -32,10 +33,17 @@ On completion the skill offers a *next step*: stop, or hand the
 recommended direction off to the `ase-task-edit`, `ase-code-craft`, or
 `ase-task-preflight` skills.
 
+##  OPTIONS
+
+`--count`|`-c=12`:
+    The *minimum* number of candidate ideas to generate in the *diverge*
+    phase before converging (default: 12). Raise it for a broader idea
+    space, lower it for a quicker, narrower session.
+
 ##  ARGUMENTS
 
 *topic*:
-    The subject to brainstorm — a feature, component, behavior, or
+    The subject to brainstorm - a feature, component, behavior, or
     design question to explore *what* to build before *how*.
 
 ##  EXAMPLES
@@ -46,6 +54,12 @@ Brainstorm an approach for a new feature:
 ❯ /ase-meta-brainstorm an offline-first sync layer for the mobile app
 ```
 
+Brainstorm with a broader idea space of at least 20 candidates:
+
+```text
+❯ /ase-meta-brainstorm --count 20 an offline-first sync layer
+```
+
 ##  SEE ALSO
 
 `ase-meta-evaluate`, `ase-meta-quorum`, `ase-meta-diaboli`

package/plugin/skills/ase-meta-diaboli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ase-meta-diaboli
-argument-hint: "[--help|-h] <thesis>"
+argument-hint: "[--help|-h] [--count|-c <count>] <thesis>"
 description: >
     Challenge a thesis by playing "Devil’s Advocate" (latin: "Advocatus
     Diaboli"). Use when the user wants a thesis or statement
@@ -12,27 +12,42 @@ effort: xhigh
 
 @${CLAUDE_SKILL_DIR}/../../meta/ase-control.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md
 
 <skill name="ase-meta-diaboli">
     Play "Devil's Advocate"
 </skill>
 
+<expand name="getopt"
+    arg1="ase-meta-diaboli"
+    arg2="--count|-c=10">
+    $ARGUMENTS
+</expand>
+
 <objective>
     Play "Devil’s Advocate" (latin: "Advocatus Diaboli") by relentlessly
-    challenging or criticising the thesis: <thesis>$ARGUMENTS</thesis>
+    challenging or criticising the thesis: <thesis><getopt-arguments/></thesis>
 </objective>
 
-1.  **Repeat Thesis**:
+Determine the minimum number of *anti-theses* to surface: set <count/>
+to <getopt-option-count/>; if <getopt-option-count/> is *non-numeric* or
+*less than or equal to 0*, use the default *10* instead.
+
+<flow>
+
+1.  <step id="STEP 1: Repeat Thesis">
 
     Output the thesis with the following <template/>:
 
     <template>
-    <ase-tpl-bullet-secondary/> **THESIS**: <thesis/>
+    <ase-tpl-bullet-normal/> **THESIS**: <thesis/>
     </template>
 
-2.  **Determine Anti-Thesis**:
+    </step>
+
+2.  <step id="STEP 2: Determine Anti-Theses">
 
-    Reason on the thesis in <thesis/> by playing *Devil’s Advocate*
+    Reason on the thesis in <thesis/> by playing *Devil's Advocate*
     (latin: *Advocatus Diaboli*) by relentlessly challenging or
     criticising it with the help of the following tenets:
 
@@ -47,7 +62,7 @@ effort: xhigh
         of polish on the surface can save what is built on top of it.
 
     -   **Target Claims, Not Person**:
-        Critique the thesis, the assumption, the evidence — never the
+        Critique the thesis, the assumption, the evidence - never the
         proponent's competence or motives, because the moment it gets
         personal, the inquiry dies.
 
@@ -103,11 +118,11 @@ effort: xhigh
     For each Anti-Thesis or Counter-Argument rank it on a Likert scale
     of 0 (weak) to 10 (strong). Repeat the process of finding more
     Anti-Theses or Counter-Arguments until you EITHER have found at
-    least 10 Anti-Theses or Counter-Arguments with at least a rank
-    of 7 OR you have already checked a total of 50 Anti-Theses or
-    Counter-Arguments.
+    least <count/> Anti-Theses or Counter-Arguments with at least a rank
+    of 7 OR you have already checked a total of <count/> x 5 Anti-Theses
+    or Counter-Arguments.
 
-    Then, for the top-10 highest-ranked Anti-Theses or
+    Then, for the top-<count/> highest-ranked Anti-Theses or
     Counter-Arguments, sort them by their rank from highest to lowest,
     store each in <antithesis-N/> with the format `**<aspect-N/>**
     (rank: <rank-N/>/10): <statement-N/>` (where <aspect-N/> is a short
@@ -120,7 +135,9 @@ effort: xhigh
     <ase-tpl-bullet-signal/> **ANTITHESIS**: <antithesis-N/>
     </template>
 
-3.  **Dialectical Reasoning**:
+    </step>
+
+3.  <step id="STEP 3: Dialectical Reasoning">
 
     Following the Hegelian dialectics of...
 
@@ -133,7 +150,7 @@ effort: xhigh
         while ignoring its own limits, gaps, or internal tensions.
 
     -   *Antithesis*: the opposing force. It is the contradiction,
-        objection, or counter-position that the thesis provokes — precisely
+        objection, or counter-position that the thesis provokes - precisely
         the role a Devil's Advocate played. The antithesis exposes what the
         thesis omitted or got wrong.
 
@@ -150,3 +167,9 @@ effort: xhigh
     <ase-tpl-bullet-normal/> **SYNTHESIS**: <synthesis/>
     </template>
 
+    Do not output any further explanations.
+
+    </step>
+
+</flow>
+

package/plugin/skills/ase-meta-diaboli/help.md

@@ -7,6 +7,7 @@
 
 `ase-meta-diaboli`
     [`--help`|`-h`]
+    [`--count`|`-c` *count*]
     *thesis*
 
 ##  DESCRIPTION
@@ -14,26 +15,37 @@
 The `ase-meta-diaboli` skill plays *Devil's Advocate* (latin:
 *Advocatus Diaboli*) by relentlessly challenging or criticising a
 supplied *thesis*. It applies a disciplined set of critical-thinking
-tenets — steelmanning, stress-testing fundamentals, surfacing implicit
+tenets - steelmanning, stress-testing fundamentals, surfacing implicit
 assumptions, demanding proportional evidence, seeking disconfirming
 cases, *Reductio Ad Absurdum*, exposing hidden costs, and pre-mortem
-thinking — while targeting the claim rather than its proponent and
+thinking - while targeting the claim rather than its proponent and
 yielding where the argument genuinely holds.
 
-The skill iterates until it has found at least ten anti-theses
+The skill iterates until it has found at least *count* anti-theses
 (counter-arguments) each ranked at least 7 on a 0 (weak) to 10
-(strong) Likert scale, reports the top ten sorted from strongest to
+(strong) Likert scale, reports the top *count* sorted from strongest to
 weakest, and finally applies *Hegelian dialectics* (*Thesis* +
 *Antithesis* → *Synthesis*) to derive a single-sentence *SYNTHESIS*
 that preserves what is true in both the thesis and its antitheses
 while discarding what is false.
 
+The `--count`/`-c` *count* option sets the minimum number of strong
+anti-theses to surface (default *10*), raising or lowering the floor of
+counter-arguments hunted for, sorted, and reported in the single
+challenge pass. A `0`, negative, or non-numeric value falls back to the
+default *10*.
+
 The intent is constructive: stress-testing the thesis in good faith to
 arrive at a better final decision, not obstructing or merely being
 contrarian.
 
 ##  ARGUMENTS
 
+`--count`, `-c` *count*:
+    Surface at least *count* strong anti-theses (default *10*) before
+    sorting and reporting the top *count* and deriving the *SYNTHESIS*. An
+    invalid or non-positive *count* reverts to the default *10*.
+
 *thesis*:
     The statement, claim, or position to be relentlessly challenged.
     It may be technical, factual, or opinion-based; the skill attacks
@@ -53,6 +65,12 @@ Stress-test a design decision:
 ❯ /ase-meta-diaboli We should rewrite the service in Rust.
 ```
 
+Surface at least fifteen anti-theses:
+
+```text
+❯ /ase-meta-diaboli --count 15 We should rewrite the service in Rust.
+```
+
 ##  SEE ALSO
 
 `ase-meta-why`, `ase-meta-evaluate`, `ase-meta-quorum`,