@rse/ase 0.9.7 → 0.9.9

package/plugin/skills/ase-code-refactor/SKILL.md

@@ -2,8 +2,8 @@
 name: ase-code-refactor
 argument-hint: "[--help|-h] [--auto|-a] [--dry|-d] [--quick|-Q] [--next|-n <option>[,...]] [<task-id>:] <request>"
 description: >
-    Refactor Code Base:
-    Use when user wants to refactor the code base.
+    Refactor Code:
+    Use when user wants to "refactor", or "change" the code base.
 user-invocable: true
 disable-model-invocation: false
 effort: xhigh
@@ -53,7 +53,9 @@ You *MUST* *NOT* call `Edit`, `Write`, `NotebookEdit`, or any
 filesystem-modifying tool during this entire skill. The *only*
 permitted way to persist artifacts is via `ase_task_save(...)`.
 
-1.  **Reason About Refactoring**:
+<flow>
+
+1.  <step id="STEP 1: Reason About Refactoring">
 
     1.  <if condition="
             <request/> matches the regexp `^[a-zA-Z][a-zA-Z0-9_-]*$`
@@ -69,20 +71,25 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         </template>
         </if>
 
-    2.  If <request/> has the format `<id/>: <text/>` where <id/> matches
-        the regexp `^[a-zA-Z][a-zA-Z0-9_-]*$`, then set
-        <request><text/></request> and <ase-task-id><id/></ase-task-id>
-        and call the `ase_task_id(id: "<ase-task-id/>", session:
-        "<ase-session-id/>")` tool from the `ase` MCP server to
-        implicitly switch the task. Do not output anything.
+    2.  <if condition="
+            <request/> has the format `<id/>: <text/>` AND
+            <id/> matches the regexp `^[a-zA-Z][a-zA-Z0-9_-]*$`
+        ">
+        Set <request><text/></request> and
+        <ase-task-id><id/></ase-task-id> and call the `ase_task_id(id:
+        "<ase-task-id/>", session: "<ase-session-id/>")` tool from the
+        `ase` MCP server to implicitly switch the task. Do not output
+        anything.
+        </if>
 
-    3.  If <request/> is empty,
-        ask the user interactively, without a special tool, for the
+    3.  <if condition="<request/> is empty">
+        Ask the user interactively, without a special tool, for the
         initial request with a single question:
 
         `**No refactoring details known yet. What is the refactoring you want to request?**`
 
         Then set <request/> to the response of the user.
+        </if>
 
     4.  <if condition="
             <ase-task-id/> is equal `default` and
@@ -109,7 +116,9 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
 
     8.  Do not output anything in this step, unless you asked the user.
 
-2.  **Investigate Code Base**:
+    </step>
+
+2.  <step id="STEP 2: Investigate Code Base">
 
     1.  Check the existing source files for all code which is related to the
         refactoring <request/>.
@@ -117,9 +126,11 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
     2.  Check the architecture of the existing code base to understand the
         overall structures and dynamics.
 
-    3.  Do not output anything in this step.
+    3.  Do not output anything in this STEP 2.
 
-3.  **Internalize Refactoring Tenets**:
+    </step>
+
+3.  <step id="STEP 3: Internalize Refactoring Tenets">
 
     You *MUST* internalize and honor the following tenets when refactoring.
     Do not output anything.
@@ -163,7 +174,9 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
             Design clear interfaces, contracts, and data models --
             with high attention to boundaries and modularity.
 
-4.  **Find Refactoring Approaches**:
+    </step>
+
+4.  <step id="STEP 4: Choose Refactoring Approaches">
 
     You *MUST* perform the following sub-steps *internally* and *without
     any output* until and including the recommendation decision. Only
@@ -198,11 +211,8 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         <template>
         ●   **APPROACH A<n/>**<annotation/>: *<summary/>*
         ○   [...]
-        ○   [...]
-        ○   [...]
-        ⊕   **PRO*: [...]
-        ⊖   **CON*: [...]
-        <optional-diagram/>
+        ⊕   **PRO**: [...]
+        ⊖   **CON**: [...]
         </template>
 
         Hints:
@@ -210,23 +220,7 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         -   Give a short one-sentence <summary/> of the refactoring
             approach plus *precise* and *ultra brief and concise*
             refactoring information. Try to keep the number of bullet
-            points (●) in the range of 1-4.
-
-        -   In case of a *complex refactoring situation* only,
-            visualize it with an optional diagram <optional-diagram/>
-            by building a Mermaid specification <mermaid-spec/>
-            (e.g. `flowchart TB`, `stateDiagram-v2`, `sequenceDiagram`,
-            `classDiagram`, or `erDiagram`, depending on intent) and
-            dispatching the rendering to the `ase-meta-diagram`
-            sub-agent by calling the tool `Agent(name: "ase-meta-diagram",
-            description: "Diagram Rendering", subagent_type:
-            "ase:ase-meta-diagram", prompt: <mermaid-spec/>)`, reproducing
-            its returned fenced code block verbatim. For *current
-            vs. proposed* comparisons, render each side as a *separate*
-            `ase-meta-diagram` invocation and stack the rendered blocks
-            *vertically* (labels `**Before:**` / `**After:**`); never
-            side-by-side. Omit <optional-diagram/> entirely for simple
-            or purely local situations.
+            points (`○ [...]`) in the range of 1-4.
 
     6.  Indicate end of reporting by showing the following <template/>:
 
@@ -234,19 +228,28 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         <ase-tpl-foot title="APPROACHES"/>
         </template>
 
-5.  **Choose Refactoring Approach**:
+    7.  <if condition="<getopt-option-auto/> is not `true`">
+
+        You *MUST* use the custom `custom-dialog` and *NOT* the
+        `AskUserQuestion`-based `user-dialog` to let the *user
+        interactively choose* the preferred approach A<n/>.
 
-    1.  If <getopt-option-auto/> is equal `false`:
-        Let the *user interactively choose* the preferred refactoring
-        approach A<n/> with the help of the <user-dialog-tool/> tool.
-        Use the header `Select Approach`, use `A<n/>: <short-summary/>`
-        for the option (where <short-summary/> is an ultra brief summary
-        of the approach A<n/>), and *single-selection* only and provide
-        small *code change previews*. Mark your recommended refactoring
-        approach with ` ⚝ **RECOMMENDATION** ⚝` here again. Except for
-        the interactive selection, do not output anything in this step.
+        Per approach A<n/>, use the option `A<n/>: <short-summary/>`
+        where <short-summary/> is an ultra brief summary of the approach
+        A<n/>. For your recommended approach, use
+        `A<n/>: ⚝ **RECOMMENDATION** ⚝: <short-summary/>` instead.
+
+        Now raise the user dialog:
+
+        <expand name="custom-dialog">
+            Select Approach: Select your preferred refactoring approach to follow?
+            A<n/>: <short-summary/>
+            [...]
+        </expand>
+
+        </if>
+        <else>
 
-    2.  If <getopt-option-auto/> is equal `true`:
         Set <n/> to the number of the refactoring approach A<n/> you recommend.
         Output a hint with the following <template/>:
 
@@ -254,7 +257,11 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ▶ status: **auto-chosen approach A<n/>**
         </template>
 
-6.  **Compose Refactoring Plan**:
+        </else>
+
+    </step>
+
+5.  <step id="STEP 5: Compose Refactoring Plan">
 
     1.  *Compose a refactoring plan* for the chosen refactoring A<n/> by
         closely aligning to the existing architecture and the existing
@@ -298,40 +305,44 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         Treat <getopt-option-next/> as a comma-separated chronological
         list of pre-selected next-step tokens. *Peek* the *first* token
         as <head/> (or `none` if the list is `none`/empty).
+        Set <args>--int-reuse-task</args>.
 
         1.  <if condition="<head/> is equal `IMPLEMENT`">
             Consume the head: set <getopt-option-next/> to the remaining
-            tokens (joined back with `,`, or `none` if empty). Set
-            <args></args> (empty).
+            tokens (joined back with `,`, or `none` if empty).
             <if condition="<getopt-option-next/> is not equal `none`">
-            Set <args>--next <getopt-option-next/></args> (forward
-            remaining list tokens to the downstream skill).
+                Set <args><args/> --next <getopt-option-next/></args>
             </if>
-            Call the tool `Skill(skill: "ase:ase-task-implement", args: <args/>)`
+            Call the tool `Skill(skill: "ase:ase-task-implement", args: "<args/>")`
             to *implement* the freshly composed plan, bypassing `ase-task-edit`.
             </if>
 
-        2.  <if condition="<head/> is equal `PREFLIGHT`">
+        2.  <elseif condition="<head/> is equal `PREFLIGHT`">
             Consume the head: set <getopt-option-next/> to the remaining
-            tokens (joined back with `,`, or `none` if empty). Set
-            <args></args> (empty).
+            tokens (joined back with `,`, or `none` if empty).
             <if condition="<getopt-option-next/> is not equal `none`">
-            Set <args>--next <getopt-option-next/></args> (forward
-            remaining list tokens to the downstream skill).
+                Set <args><args/> --next <getopt-option-next/></args>
             </if>
-            Call the tool `Skill(skill: "ase:ase-task-preflight", args: <args/>)`
+            Call the tool `Skill(skill: "ase:ase-task-preflight", args: "<args/>")`
             to *preflight* the freshly composed plan, bypassing `ase-task-edit`.
-            </if>
+            </elseif>
 
-        3.  <if condition="
-                <head/> is not equal `IMPLEMENT` AND
-                <head/> is not equal `PREFLIGHT`
-            ">
-            Forward the *entire* (unshifted) list to `ase-task-edit`, which
-            will consume its head itself. Set <args></args> (empty).
-            <if condition="<getopt-option-next/> is not equal `none`">
-            Set <args>--next <getopt-option-next/></args> (append to args).
+        3.  <else>
+            Hand off to `ase-task-edit`.
+            <if condition="<head/> is equal `EDIT`">
+                Consume the head: set <getopt-option-next/> to the remaining
+                tokens (joined back with `,`, or `none` if empty).
             </if>
-            Then call the tool `Skill(skill: "ase:ase-task-edit", args: <args/>)`.
+            All remaining tokens are `ase-task-edit`'s own vocabulary
+            and are forwarded verbatim, so `ase-task-edit` consumes its
+            head itself.
+            <if condition="<getopt-option-next/> is not equal `none`">
+                Set <args><args/> --next <getopt-option-next/></args>
             </if>
+            Then call the tool `Skill(skill: "ase:ase-task-edit", args: "<args/>")`.
+            </else>
+
+    <step>
+
+</flow>
 

package/plugin/skills/ase-code-refactor/help.md

@@ -86,5 +86,5 @@ Refactor under a named task and directly hand off to implementation:
 
 ##  SEE ALSO
 
-`ase-code-craft`, `ase-code-resolve`, `ase-task-edit`,
-`ase-task-preflight`, `ase-task-implement`.
+[`ase-code-craft`](../ase-code-craft/help.md), [`ase-code-resolve`](../ase-code-resolve/help.md), [`ase-task-edit`](../ase-task-edit/help.md),
+[`ase-task-preflight`](../ase-task-preflight/help.md), [`ase-task-implement`](../ase-task-implement/help.md).

package/plugin/skills/ase-code-resolve/SKILL.md

@@ -3,7 +3,7 @@ name: ase-code-resolve
 argument-hint: "[--help|-h] [--auto|-a] [--dry|-d] [--quick|-Q] [--next|-n <option>[,...]] [<task-id>:] <problem>"
 description: >
     Resolve Problem:
-    Use when user wants a bug fixed or problem resolved.
+    Use when user wants to "bugfix" or "fix" code or "resolve" a problem.
 user-invocable: true
 disable-model-invocation: false
 effort: xhigh
@@ -53,7 +53,9 @@ You *MUST* *NOT* call `Edit`, `Write`, `NotebookEdit`, or any
 filesystem-modifying tool during this entire skill. The *only*
 permitted way to persist artifacts is via `ase_task_save(...)`.
 
-1.  **Reason About Problem**:
+<flow>
+
+1.  <step id="STEP 1: Reason About Problem">
 
     1.  If <problem/> matches the regexp `^[PT]\d+$` (i.e. a bare issue
         identifier like `P1`, `P2`, `T1`, `T2`, ...),
@@ -81,20 +83,26 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         </template>
         </if>
 
-    3.  If <problem/> has the format `<id/>: <text/>` where <id/> matches
-        the regexp `^[a-zA-Z][a-zA-Z0-9_-]*$`, then set
-        <problem><text/></problem> and <ase-task-id><id/></ase-task-id>
-        and call the `ase_task_id(id: "<ase-task-id/>", session:
-        "<ase-session-id/>")` tool from the `ase` MCP server to
-        implicitly switch the task. Do not output anything.
+    3.  <if condition="
+            <problem-id/> is not set AND
+            <problem/> has the format `<id/>: <text/>` AND
+            <id/> matches the regexp `^[a-zA-Z][a-zA-Z0-9_-]*$`
+        ">
+        Set <problem><text/></problem> and
+        <ase-task-id><id/></ase-task-id> and call the `ase_task_id(id:
+        "<ase-task-id/>", session: "<ase-session-id/>")` tool from the
+        `ase` MCP server to implicitly switch the task. Do not output
+        anything.
+        </if>
 
-    4.  If <problem/> is empty,
-        ask the user interactively, without a special tool, for the
+    4.  <if condition="<problem/> is empty">
+        Ask the user interactively, without a special tool, for the
         initial problem with a single question:
 
         `**No problem details known yet. What is the problem you want to resolve?**`
 
         Then set <problem/> to the response of the user.
+        </if>
 
     5.  <if condition="
             <ase-task-id/> is equal `default` and
@@ -160,7 +168,9 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
           verbatim. Omit <optional-diagram/> entirely for simple or
           purely local situations.
 
-2.  **Investigate Code Base**:
+    </step>
+
+2.  <step id="STEP 2: Investigate Code Base">
 
     1.  Check the existing source files for all code which is related to the
         requested <problem/> resolution.
@@ -168,9 +178,11 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
     2.  Check the architecture of the existing code base to understand the
         overall structures and dynamics.
 
-    3.  Do not output anything in this step.
+    3.  Do not output anything in this STEP 2.
+
+    </step>
 
-3.  **Internalize Problem Resolution Tenets**:
+3.  <step id="STEP 3: Internalize Problem Resolution Tenets">
 
     You *MUST* internalize and honor the following tenets when resolving the problem.
     Do not output anything.
@@ -212,7 +224,9 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
             *theoretical, fictive, or unexpected* errors *should* be
             handled more generally and in parent scopes.
 
-4.  **Find Problem Resolution Approaches**:
+    </step>
+
+4.  <step id="STEP 4: Choose Problem Resolution Approaches">
 
     You *MUST* perform the following sub-steps *internally* and *without
     any output* until and including the recommendation decision. Only
@@ -247,35 +261,16 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         <template>
         ●   **APPROACH A<n/>**<annotation/>: *<summary/>*
         ○   [...]
-        ○   [...]
-        ○   [...]
-        ⊕   *PRO*: [...]
-        ⊖   *CON*: [...]
-        <optional-diagram/>
+        ⊕   **PRO**: [...]
+        ⊖   **CON**: [...]
         </template>
 
         Hints:
 
         -   Give a short one-sentence <summary/> of the resolution
             approach plus *precise* and *ultra brief and concise*
-            resolution information. Try to keep the number of bullet
-            points (●) in the range of 1-4.
-
-        -   In case of a *complex resolution situation* only,
-            visualize it with an optional diagram <optional-diagram/>
-            by building a Mermaid specification <mermaid-spec/>
-            (e.g. `flowchart TB`, `stateDiagram-v2`, `sequenceDiagram`,
-            `classDiagram`, or `erDiagram`, depending on intent) and
-            dispatching the rendering to the `ase-meta-diagram`
-            sub-agent by calling the tool `Agent(name: "ase-meta-diagram",
-            description: "Diagram Rendering", subagent_type:
-            "ase:ase-meta-diagram", prompt: <mermaid-spec/>)`, reproducing
-            its returned fenced code block verbatim. For *current
-            vs. proposed* comparisons, render each side as a *separate*
-            `ase-meta-diagram` invocation and stack the rendered blocks
-            *vertically* (labels `**Before:**` / `**After:**`); never
-            side-by-side. Omit <optional-diagram/> entirely for simple
-            or purely local situations.
+            resolution information. Try to keep the number of bullet points
+            (`○ [...]`) in the range of 1-4.
 
     6.  Indicate end of reporting by showing the following <template/>:
 
@@ -283,18 +278,28 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         <ase-tpl-foot title="APPROACHES"/>
         </template>
 
-5.  **Choose Problem Resolution Approach**:
+    7.  <if condition="<getopt-option-auto/> is not `true`">
 
-    1.  If <getopt-option-auto/> is equal `false`:
-        Let the *user interactively choose* the preferred resolution
-        approach A<n/> with the help of the <user-dialog-tool/> tool.
-        Use the header `Select Approach`, use `A<n/>: <short-summary/>`
-        for the option (where <short-summary/> is an ultra brief summary
-        of the approach A<n/>), and *single-selection* only and provide
-        small *code change previews*. Mark your recommended resolution
-        approach with ` ⚝ **RECOMMENDATION** ⚝` here again.
+        You *MUST* use the custom `custom-dialog` and *NOT* the
+        `AskUserQuestion`-based `user-dialog` to let the *user
+        interactively choose* the preferred approach A<n/>.
+
+        Per approach A<n/>, use the option `A<n/>: <short-summary/>`
+        where <short-summary/> is an ultra brief summary of the approach
+        A<n/>. For your recommended approach, use
+        `A<n/>: ⚝ **RECOMMENDATION** ⚝: <short-summary/>` instead.
+
+        Now raise the user dialog:
+
+        <expand name="custom-dialog">
+            Select Approach: Select your preferred resolution approach to follow?
+            A<n/>: <short-summary/>
+            [...]
+        </expand>
+
+        </if>
+        <else>
 
-    2.  If <getopt-option-auto/> is equal `true`:
         Set <n/> to the number of the resolution approach A<n/> you recommend.
         Output a hint with the following <template/>:
 
@@ -302,7 +307,11 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ▶ status: **auto-chosen approach A<n/>**
         </template>
 
-6.  **Compose Problem Resolution Plan**:
+        </else>
+
+    </step>
+
+5.  <step id="STEP 5: Compose Problem Resolution Plan">
 
     1.  *Compose a plan* with code references, a precise description of the
         problem, the chosen resolution approach, a preview of the *unified
@@ -336,7 +345,7 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         `ase_task_save(id: "<ase-task-id/>", text: "<content/>")`.
 
     4.  If <problem-id/> is set (i.e. the <problem/> was retrieved from
-        `ase_kv_get` in STEP 1.3 via key `ase-issue-<problem-id/>`),
+        `ase_kv_get` in STEP 1.1 via key `ase-issue-<problem-id/>`),
         you *MUST* additionally call the `ase_kv_delete(key:
         "ase-issue-<problem-id/>")` tool of the `ase` MCP
         server to remove the now-resolved analyzer result from the
@@ -353,40 +362,44 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         Treat <getopt-option-next/> as a comma-separated chronological
         list of pre-selected next-step tokens. *Peek* the *first* token
         as <head/> (or `none` if the list is `none`/empty).
+        Set <args>--int-reuse-task</args>.
 
         1.  <if condition="<head/> is equal `IMPLEMENT`">
             Consume the head: set <getopt-option-next/> to the remaining
-            tokens (joined back with `,`, or `none` if empty). Set
-            <args></args> (empty).
+            tokens (joined back with `,`, or `none` if empty).
             <if condition="<getopt-option-next/> is not equal `none`">
-            Set <args>--next <getopt-option-next/></args> (forward
-            remaining list tokens to the downstream skill).
+                Set <args><args/> --next <getopt-option-next/></args>
             </if>
-            Call the tool `Skill(skill: "ase:ase-task-implement", args: <args/>)`
+            Call the tool `Skill(skill: "ase:ase-task-implement", args: "<args/>")`
             to *implement* the freshly composed plan, bypassing `ase-task-edit`.
             </if>
 
-        2.  <if condition="<head/> is equal `PREFLIGHT`">
+        2.  <elseif condition="<head/> is equal `PREFLIGHT`">
             Consume the head: set <getopt-option-next/> to the remaining
-            tokens (joined back with `,`, or `none` if empty). Set
-            <args></args> (empty).
+            tokens (joined back with `,`, or `none` if empty).
             <if condition="<getopt-option-next/> is not equal `none`">
-            Set <args>--next <getopt-option-next/></args> (forward
-            remaining list tokens to the downstream skill).
+                Set <args><args/> --next <getopt-option-next/></args>
             </if>
-            Call the tool `Skill(skill: "ase:ase-task-preflight", args: <args/>)`
+            Call the tool `Skill(skill: "ase:ase-task-preflight", args: "<args/>")`
             to *preflight* the freshly composed plan, bypassing `ase-task-edit`.
-            </if>
+            </elseif>
 
-        3.  <if condition="
-                <head/> is not equal `IMPLEMENT` AND
-                <head/> is not equal `PREFLIGHT`
-            ">
-            Forward the *entire* (unshifted) list to `ase-task-edit`, which
-            will consume its head itself. Set <args></args> (empty).
-            <if condition="<getopt-option-next/> is not equal `none`">
-            Set <args>--next <getopt-option-next/></args> (append to args).
+        3.  <else>
+            Hand off to `ase-task-edit`.
+            <if condition="<head/> is equal `EDIT`">
+                Consume the head: set <getopt-option-next/> to the remaining
+                tokens (joined back with `,`, or `none` if empty).
             </if>
-            Then call the tool `Skill(skill: "ase:ase-task-edit", args: <args/>)`.
+            All remaining tokens are `ase-task-edit`'s own vocabulary
+            and are forwarded verbatim, so `ase-task-edit` consumes its
+            head itself.
+            <if condition="<getopt-option-next/> is not equal `none`">
+                Set <args><args/> --next <getopt-option-next/></args>
             </if>
+            Then call the tool `Skill(skill: "ase:ase-task-edit", args: "<args/>")`.
+            </else>
+
+    <step>
+
+</flow>
 

package/plugin/skills/ase-code-resolve/help.md

@@ -92,6 +92,6 @@ Resolve a previously analyzed issue and hand off to implementation:
 
 ##  SEE ALSO
 
-`ase-code-craft`, `ase-code-refactor`, `ase-code-analyze`,
-`ase-arch-analyze`, `ase-task-edit`, `ase-task-preflight`,
-`ase-task-implement`.
+[`ase-code-craft`](../ase-code-craft/help.md), [`ase-code-refactor`](../ase-code-refactor/help.md), [`ase-code-analyze`](../ase-code-analyze/help.md),
+[`ase-arch-analyze`](../ase-arch-analyze/help.md), [`ase-task-edit`](../ase-task-edit/help.md), [`ase-task-preflight`](../ase-task-preflight/help.md),
+[`ase-task-implement`](../ase-task-implement/help.md).

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

@@ -122,7 +122,7 @@ explicitly requested by this procedure via outputs based on a <template/>!
         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.
+        than or equal to 0*, use the default *5* instead.
 
     You *MUST* *NOT* output anything in this STEP 2.
 

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

@@ -32,15 +32,15 @@ one block per point, each showing its *LOCATION*, *EVIDENCE*,
 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
+most *N* points (default *5*). 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*.
+non-numeric value falls back to the default *5*.
 
 ##  ARGUMENTS
 
 `--top`, `-t` *N*:
-    Bound the ranked list to at most *N* key points (default *10*). The
+    Bound the ranked list to at most *N* key points (default *5*). 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.
@@ -72,5 +72,5 @@ Distill a pasted block of text:
 
 ##  SEE ALSO
 
-`ase-meta-search`, `ase-docs-proofread`, `ase-meta-why`.
+[`ase-meta-search`](../ase-meta-search/help.md), [`ase-docs-proofread`](../ase-docs-proofread/help.md), [`ase-meta-why`](../ase-meta-why/help.md).