@rse/ase 0.9.62 → 0.9.64

package/plugin/meta/ase-tenets.md

@@ -6,7 +6,7 @@ The following are the **ASE Tenets** -- the guiding principles you
 *MUST* internalize when requested. They are organized into *Generic
 Tenets*, which always apply, and *Operation-Specific Tenets*, which
 apply only to a particular kind of operation (Crafting, Reconciling,
-Refactoring, Resolving).
+Refactoring, Resolving, Specifying).
 
 GENERIC TENETS
 --------------
@@ -149,11 +149,11 @@ you *MUST* honor the following so-called **RECONCILIATION TENETS**:
 -   **Level-Appropriate Translation**:
     Re-express source facts at the *target's* level of abstraction and
     altitude; do not copy verbatim across artifact levels. A SPEC states
-    intent, an ARCH states structure, CODE states realization, DOCS
-    states facts, etc. -- align the *meaning*, not the wording.
+    intent and structure, CODE states realization, DOCS states facts,
+    etc. -- align the *meaning*, not the wording.
 
 -   **Format Conformance**:
-    Keep every formatted target (SPEC, ARCH, TASK) conformant to its
+    Keep every formatted target (SPEC, TASK) conformant to its
     format contract (headings, structure, identifiers). Treat CODE,
     DOCS, INFR, and OTHR kinds of artifacts as foreign-defined, but not
     as free-form.
@@ -221,3 +221,62 @@ you *MUST* honor the following so-called **RESOLVING TENETS**:
     handled *near the origin*. Problems for *theoretical, fictive, or
     unexpected* errors *should* be handled more generally and in parent
     scopes.
+
+SPECIFYING TENETS
+-----------------
+
+When *specifying* -- creating, revising, or editing the statements of a
+specification artifact set -- you *MUST* honor the following so-called
+**SPECIFYING TENETS**:
+
+-   **Intent over Realization**:
+    A specification, in its domain-specific and non-architecture related
+    aspects, states only the *WHAT* and the *WHY*, never the *HOW*.
+    Record intent, structure, constraints, and relationships here.
+    Implementation steps, algorithms, technologies, and code-level
+    details describe the *WHAT* and *HOW* and belong only into
+    the domain-unspecific and architecture-related aspects of the
+    specification.
+
+-   **Statement with Rationale**:
+    Every statement carries its *WHY* behind the `, BECAUSE ` clause in
+    a description. A statement without a rationale can neither be judged
+    nor revised, so never leave the rationale implicit and never restate
+    the statement as its own rationale.
+
+-   **Unambiguous and Verifiable**:
+    Every statement is precise enough that two readers derive the same
+    meaning and that its fulfillment is decidable. Replace vague
+    qualifiers ("fast", "user-friendly", "robust") with the concrete
+    property, threshold, or scenario actually meant.
+
+-   **Single Source of Truth**:
+    Every fact resides in exactly *one* object of the specification. Do
+    not restate a fact in a second place -- point at its owning object
+    with a `[[xxx]]` reference instead, so a later change has exactly
+    one place to land.
+
+-   **Atomic Statement**:
+    Every statement expresses exactly *one* fact with exactly *one*
+    rationale. Split a statement that joins independent facts with
+    "and"/"or" -- otherwise its fulfillment is only partially decidable
+    and its rationale covers more than it explains.
+
+-   **Schema Conformance**:
+    Every object stays conformant to the **SpecBook SCHEMA Model** of
+    the project: allowed kinds, allowed nesting, mandatory and optional
+    properties, and the configured value constraints. Never invent an
+    object kind or a property key the schema does not define.
+
+-   **Referential Integrity**:
+    Every `[[xxx]]` reference resolves to exactly one object. When an
+    object is renamed, moved, or removed, follow *all* references to it
+    through the entire specification corpus and adjust or remove them
+    in the same change set -- a dangling or ambiguous reference is a
+    defect.
+
+-   **No Fabrication**:
+    Never invent specification content the request does not warrant. If
+    the request is silent, ambiguous, or contradictory on something the
+    specification needs, surface the gap explicitly rather than papering
+    over it with a plausible guess.

package/plugin/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "https://ase.tools",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "https://github.com/rse/ase/issues" },
-    "version":                              "0.9.62",
+    "version":                              "0.9.64",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -15,9 +15,10 @@
     },
     "devDependencies": {
         "@rse/stx":                         "1.1.6",
+        "@rse/specbook":                    "1.0.3",
         "markdownlint":                     "0.41.1",
         "markdownlint-cli2":                "0.23.2",
-        "eslint":                           "10.9.0",
+        "eslint":                           "10.9.1",
         "@eslint/markdown":                 "8.0.3",
         "eslint-markdown":                  "0.14.0"
     },
@@ -25,6 +26,9 @@
         "npm":                              ">=10.0.0",
         "node":                             ">=22.13.0"
     },
+    "allowScripts": {
+        "fsevents":                         true
+    },
     "scripts": {
         "start":                            "stx -v4 -l warning -c etc/stx.conf"
     }

package/plugin/skills/ase-arch-analyze/help.md

@@ -40,6 +40,13 @@ covers the *entire* `ase-issue-*` space, including any prefixed results.
     A file, directory, or other reference to the source code that
     is to be analyzed architecturally.
 
+##  SCENARIOS
+
+-   You want the software architecture of your code base reviewed
+-   You want coupling and cohesion problems between packages found
+-   You want an architecture diagram plus PROBLEM and TRADEOFF findings
+-   You want architecture findings persisted for later resolution
+
 ##  EXAMPLES
 
 Analyze architecture of the current project:

package/plugin/skills/ase-arch-discover/help.md

@@ -57,6 +57,13 @@ demotes dependency-heavy components.
     A short description of the desired functionality the third-party
     component should provide.
 
+##  SCENARIOS
+
+-   You want a third-party library or framework for a needed functionality
+-   You want a ranked survey of candidate components from NPM or Maven Central
+-   You want to know whether a package is healthy or stale and abandoned
+-   You want to decide between a dependency and hand-rolling a small feature
+
 ##  EXAMPLES
 
 Discover components for JSON schema validation:

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

@@ -61,6 +61,14 @@ fixed via `ase-code-edit P<n>`.
     A file, directory, function, or other reference to the source code
     to analyze.
 
+##  SCENARIOS
+
+-   You want your code checked for logic, semantics, and control-flow problems
+-   You want a read-only report of problems without any changes applied
+-   You want performance and efficiency opportunities surfaced
+-   You want a security-focused inspection of your code
+-   You want problems persisted as issue ids like `P1` for later resolving
+
 ##  EXAMPLES
 
 Analyze a specific source file for logic/semantic problems:

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

@@ -89,6 +89,13 @@ entirely and applies the change set to the affected artifacts itself.
     a *task-id* followed by a colon to bind the resulting plan to
     a specific task id.
 
+##  SCENARIOS
+
+-   You want to add a new feature to the code base
+-   You want feature approaches with pros and cons before any code changes
+-   You want a task plan composed for building something new
+-   You want a fast one-shot crafting without any plan ceremony
+
 ##  EXAMPLES
 
 Craft a new logging feature:

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

@@ -89,6 +89,13 @@ cleanly and are then reported as failed; stage everything and use
 The worktree names are *not* argument-driven: they are always derived
 from the *current* project id and the per-part feature slug.
 
+##  SCENARIOS
+
+-   You want a large uncommitted change set split into atomic parts
+-   You want each cohesive part of a diff in its own Git worktree
+-   You want mixed-up changes untangled before committing them
+-   You want a preview of how a change set would be divided
+
 ##  EXAMPLES
 
 Dissect the current working copy changes:

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

@@ -189,9 +189,11 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
         2.  DETERMINE QUESTIONS:
 
-            Determine the questions, comprised of a globally-unique id
-            <question-N-id/> of `Q<N/>`, and a very brief but precise
-            question text <question-N-text/>. Each question is chosen to
+            Determine the questions, comprised of a round-local id
+            <question-N-id/> of `Q<N/>` -- where <N/> restarts at `1`
+            in *every* round, independent of the numbering of previous
+            rounds --, and a very brief but precise question text
+            <question-N-text/>. Each question is chosen to
             resolve the open points related to the above understanding
             of grilling, by focusing on the mentioned *Focus Areas*.
 
@@ -229,9 +231,10 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             Finally, *sort* the questions by descending focus area
             order -- first all `DOMAIN`, then all `INTERFACE`, then all
             `ARCHITECTURE`, and then all `IMPLEMENTATION` ones -- and
-            renumber <N/> according to this order. Truncate the list
-            after a maximum of 10 questions and set <n/> to the number
-            of remaining questions. Do not output anything.
+            renumber <N/> according to this order, starting at `1`.
+            Truncate the list after a maximum of 10 questions and set
+            <n/> to the number of remaining questions. Do not output
+            anything.
 
             Finally, assemble the <question-N/> out of
             `**<question-N-id/>** ▶ **<context-N-id/>** ▷
@@ -241,8 +244,10 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
             For all remaining <question-N/>, check the code base and
             your world knowledge to find *two to three* grounded answer
-            alternatives <answer-N-K/> with an id <answer-N-K-id/>
-            of `A<K/>`, a 1-3 word label <answer-N-K-label/>, and
+            alternatives <answer-N-K/> with a question-local id
+            <answer-N-K-id/> of `A<K/>` -- where <K/> restarts at `1`
+            for *every* question, independent of the numbering of other
+            questions --, a 1-3 word label <answer-N-K-label/>, and
             an ultra brief description <answer-N-K-description/> of
             at most *10 words*. For the answer which reflects the
             current <todo-what/>/<todo-how/> understanding, append
@@ -304,7 +309,7 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
                 | [...]         | [...]       |
 
                 Legend: **DOM**: Domain (MUST), **IFC**: Interface (MUST), **ARC**: Architecture (SHOULD), **IMP**: Implementation (MAY)
-                        **Qn**: global question id, **An**: question-local answer id, ⚑: current decision state
+                        **Qn**: round-local question id, **An**: question-local answer id, ⚑: current decision state
                 </template>
 
             2.  Show a custom dialog. Its only answer options are the

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

@@ -101,6 +101,13 @@ implementation until it passes). The *querying* state and every
     for the query via an interactive `Edit Query` dialog, carrying the
     fixed `STOP SKILL` option plus free-text input.
 
+##  SCENARIOS
+
+-   You want the code base edited in one shot from a plain description
+-   You want an analyzer issue like `P1` fixed directly without a plan
+-   You want a quick change with optional grilling and verification
+-   You want several edits chained in a loop, optionally in a worktree
+
 ##  EXAMPLES
 
 Edit in one shot, without any questions or verification:

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

@@ -24,6 +24,13 @@ notice), and *GOTCHAS* (what to not stumble over).
     A file, directory, function, or other reference to the source code
     to explain.
 
+##  SCENARIOS
+
+-   You want to understand how a piece of code works
+-   You want an explanation with WHAT, WHY, analogy, and diagram
+-   You want the cruxes and gotchas of unfamiliar code pointed out
+-   You want a quick orientation before touching foreign code
+
 ##  EXAMPLES
 
 Explain a single source file:

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

@@ -24,6 +24,13 @@ a *MODULE STRUCTURE* Mermaid diagram of modules and their imports.
     One or more file or directory references to source code that
     should be inspected for insights.
 
+##  SCENARIOS
+
+-   You want a high-level overview of a project
+-   You want to know who wrote the project and which files churn most
+-   You want a module structure diagram of the imports
+-   You want to get familiar with an unknown code base quickly
+
 ##  EXAMPLES
 
 Get insights into the current project:

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

@@ -81,6 +81,14 @@ the code, and comments contradicting the code.
 *source-reference*:
     A file, directory, or other reference to the source code to lint.
 
+##  SCENARIOS
+
+-   You want your code checked for code quality problems
+-   You want corrections proposed which you accept or reject one by one
+-   You want all quality corrections applied automatically
+-   You want only specific quality aspects like formatting or spelling checked
+-   You want missing or excessive code documentation flagged
+
 ##  EXAMPLES
 
 Lint a source file interactively:

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

@@ -82,6 +82,13 @@ entirely and applies the change set to the affected artifacts itself.
     with a *task-id* followed by a colon to bind the resulting plan
     to a specific task id.
 
+##  SCENARIOS
+
+-   You want existing code restructured without changing its behavior
+-   You want refactoring approaches with pros and cons before any changes
+-   You want a task plan composed for a cleanup
+-   You want a one-shot refactoring applied directly in place
+
 ##  EXAMPLES
 
 Refactor a module into smaller files:

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

@@ -88,6 +88,13 @@ entirely and applies the change set to the affected artifacts itself.
     skill. Optionally prefixed with a *task-id* followed by a colon
     to bind the resulting plan to a specific task id.
 
+##  SCENARIOS
+
+-   You want a bug fixed or a problem resolved in the code
+-   You want an issue like `P1` reported by an analyzer resolved
+-   You want resolution approaches with pros and cons before any changes
+-   You want a task plan composed for a bugfix
+
 ##  EXAMPLES
 
 Resolve a free-text problem:

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

@@ -52,6 +52,13 @@ non-numeric value falls back to the default *5*.
     *text* itself pasted inline. If it resolves to a readable file the
     file is read; otherwise it is treated verbatim as pasted text.
 
+##  SCENARIOS
+
+-   You want the key points of a document extracted and ranked
+-   You want the essence of a long text without reading all of it
+-   You want each key point backed by verbatim, line-cited evidence
+-   You want a pasted text or file boiled down to what matters
+
 ##  EXAMPLES
 
 Distill the key points of a document file:

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

@@ -36,6 +36,13 @@ hint, which re-proposes the correction without limit) or - with
     A file, directory, or other reference to the documents to
     proofread.
 
+##  SCENARIOS
+
+-   You want documents checked for spelling, punctuation, and grammar
+-   You want corrections proposed which you accept or reject one by one
+-   You want a whole documentation directory corrected automatically
+-   You want a final language pass over a text before publishing
+
 ##  EXAMPLES
 
 Proofread a single document interactively:

package/plugin/skills/ase-help-intent/SKILL.md

@@ -3,11 +3,12 @@ name: ase-help-intent
 argument-hint: "[--help|-h] <intent>"
 description: >
     Match a free-text intent against the accumulated help of all ASE
-    skills, generate the single best-fitting `/ase:ase-xxx-xxx` command
-    with concrete options and arguments, and let the user execute it,
-    refine the intent, or cancel. Use when the user knows what they want
-    but not which skill or flags realize it, or mentions "intent" or
-    requests "help".
+    skills, generate all adequately fitting `/ase:ase-xxx-xxx` commands
+    -- ranked best-fitting first, each with concrete options and
+    arguments -- and let the user execute one of them, refine the
+    intent, or cancel. Use when the user knows what they want but not
+    which skill or flags realize it, or mentions "intent" or requests
+    "help".
 user-invocable: true
 disable-model-invocation: false
 effort: high
@@ -21,7 +22,7 @@ allowed-tools:
 @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md
 
 <purpose name="ase-help-intent">
-Match an Intent to an ASE Command
+Match an Intent to ASE Commands
 </purpose>
 
 <expand name="getopt"
@@ -32,8 +33,8 @@ Match an Intent to an ASE Command
 
 <objective>
 *Match* the following free-text intent against the accumulated help of
-all ASE skills and *generate* the single best-fitting `/ase:ase-xxx-xxx`
-command that realizes it:
+all ASE skills and *generate* every adequately fitting `/ase:ase-xxx-xxx`
+command that realizes it, ranked best-fitting first:
 <intent><getopt-arguments/></intent>
 </objective>
 
@@ -63,32 +64,43 @@ catalog you match <intent/> against:
 2.  <step id="STEP 2: Match Intent and Dialog">
 
     *REPEAT* the following sub-steps in a *LOOP* until the user either
-    *executes* the generated command or *cancels* the dialog in sub-step 4:
+    *executes* one of the generated commands or *cancels* the dialog in
+    sub-step 4:
 
     1.  *Match Intent*:
 
-        Match the current <intent/> against the <corpus/> and select the
-        *single* best-fitting skill. From that skill's `##  SYNOPSIS`,
-        `##  OPTIONS`, and `##  ARGUMENTS` sections in <corpus/>,
-        *generate* a concrete command that realizes <intent/>:
-
-        -   Set <name/> to the selected skill's name (e.g. `ase-code-lint`).
-        -   Set <arguments/> to the concrete option flags and positional
-            arguments -- derived from the skill's `##  OPTIONS` and
-            `##  ARGUMENTS` -- that best realize <intent/> (may be empty).
-        -   Set <command>/ase:<name/> <arguments/></command> (the full
-            command line, with surplus inner spaces collapsed).
-        -   Set <rationale/> to a *very brief*, single-sentence
-            justification of why the selected skill and its options match
+        Match the current <intent/> against the <corpus/> and select
+        *every* skill that adequately fits it -- judging the fit
+        primarily by each skill's `##  SCENARIOS` ("You want ...") and
+        `##  DESCRIPTION` sections. Order the selected skills from
+        best-fitting to worst-fitting and keep at most the *8* best
+        ones, so the dispatch dialog of sub-step 4 stays addressable.
+        Set <count/> to the number of kept skills. Then, for each kept
+        skill <n/> (numbered `1` to <count/> in rank order), from that
+        skill's `##  SYNOPSIS`, `##  OPTIONS`, and `##  ARGUMENTS`
+        sections in <corpus/>, *generate* a concrete command that
+        realizes <intent/>:
+
+        -   Set <name<n/>/> to the skill's name (e.g. `ase-code-lint`).
+        -   Set <arguments<n/>/> to the concrete option flags and
+            positional arguments -- derived from the skill's
+            `##  OPTIONS` and `##  ARGUMENTS` -- that best realize
+            <intent/> (may be empty).
+        -   Set <command<n/>>/ase:<name<n/>/> <arguments<n/>/></command<n/>>
+            (the full command line, with surplus inner spaces collapsed).
+        -   Set <rationale<n/>/> to a *very brief*, single-sentence
+            justification of why this skill and its options match
             <intent/>.
-        -   Set <matched>yes</matched>.
+
+        Finally set <matched>yes</matched>.
 
     2.  *Guard No Match*:
 
         <if condition="no skill in <corpus/> adequately matches <intent/>">
         Set <matched>no</matched> and discard the inadequate selection of
-        sub-step 1 by setting <name></name>, <arguments></arguments>, and
-        <command></command> (all set to empty), so that no stale command
+        sub-step 1 by setting <count>0</count> and clearing all
+        <name<n/>/>, <arguments<n/>/>, and <command<n/>/> placeholders
+        (all set to empty), so that no stale command
         can survive into the dialog of sub-step 4. Then output the
         following <template/> and *continue* the *loop* at sub-step 4 to
         prompt the user for a refined or clearer intent via the dialog's
@@ -99,18 +111,22 @@ catalog you match <intent/> against:
         </template>
         </if>
 
-    3.  *Render Command*:
+    3.  *Render Commands*:
 
-        Output the generated command with the following <template/>:
+        Output the generated commands, in rank order, with the following
+        <template/>, where the `[...]` marks the repetition of the
+        command/rationale line pair for each kept skill <n/> from `1`
+        to <count/>:
 
         <template>
-        <ase-tpl-head title="SKILL COMMAND PROPOSAL"/>
+        <ase-tpl-head title="SKILL COMMAND PROPOSALS"/>
 
-        ❯ `<command/>`
+        **C<n/>** ❯ `<command<n/>/>`
+           ▷ *<rationale<n/>/>*
 
-        <ase-tpl-foot title="SKILL COMMAND PROPOSAL"/>
+        [...]
 
-        **RATIONALE**: <rationale/>
+        <ase-tpl-foot title="SKILL COMMAND PROPOSALS"/>
         </template>
 
     4.  *Dispatch Command*:
@@ -123,9 +139,9 @@ catalog you match <intent/> against:
         Let the user decide how to proceed by raising a question with the
         following custom dialog (invoked with `--other`, so that any
         free-text instruction is accepted as an intent refinement). Which
-        dialog is raised depends on <matched/>, so that `EXECUTE` is
-        offered *only* when a command was actually generated in sub-step 1
-        *and* rendered in sub-step 3:
+        dialog is raised depends on <matched/>, so that the `C<n/>`
+        command options are offered *only* when commands were actually
+        generated in sub-step 1 *and* rendered in sub-step 3:
 
         <if condition="<matched/> is `no`">
         <expand name="custom-dialog" arg1="--other">
@@ -136,10 +152,16 @@ catalog you match <intent/> against:
         </if>
         <else>
         <expand name="custom-dialog" arg1="--other">
-            Dispatch: What would you like to do with the generated command?
-            EXECUTE: Execute the generated command now.
-            CANCEL:  Cancel this dialog.
+            Dispatch: Which of the proposed commands would you like to execute?
+            C1: Execute: `<command1/>`
+            [...]
+            CANCEL: Cancel this dialog.
         </expand>
+
+        The `[...]` line stands for one further answer line
+        `C<n/>: Execute `<command<n/>/>` now.` per additionally kept
+        skill <n/> from `2` to <count/>, in rank order, so the dialog
+        offers exactly <count/> command options plus `CANCEL`.
         </else>
 
         Check the tool <result/> and dispatch accordingly:
@@ -148,7 +170,7 @@ catalog you match <intent/> against:
             *Break* out of the *loop* and stop processing without any
             further output.
 
-        -   If <result/> is `REFINE`, or <result/> is `EXECUTE` while
+        -   If <result/> is `REFINE`, or <result/> matches `C<n/>` while
             <matched/> is `no`: do *not* execute anything -- output the
             following <template/> and *continue* the *loop* at sub-step 4
             to obtain a refined intent via the dialog's free-text channel:
@@ -157,13 +179,14 @@ catalog you match <intent/> against:
             <ase-tpl-bullet-secondary/> **HINT**: please enter a refined or clearer intent as free text.
             </template>
 
-        -   If <result/> is `EXECUTE` (which implies <matched/> is `yes`):
-            *Break* out of the *loop*, output the following <template/>,
-            and then call the tool `Skill(skill: "ase:<name/>", args:
-            "<arguments/>")` to *execute* the generated command:
+        -   If <result/> matches `C<n/>` (which implies <matched/> is
+            `yes`): *Break* out of the *loop*, output the following
+            <template/>, and then call the tool `Skill(skill:
+            "ase:<name<n/>/>", args: "<arguments<n/>/>")` to *execute*
+            the selected command:
 
             <template>
-            ⧉ **ASE**: ◉ intent: **<intent/>**, ⌘ command: **<command/>**, ▶ status: **command executing**
+            ⧉ **ASE**: ◉ intent: **<intent/>**, ⌘ command: **<command<n/>/>**, ▶ status: **command executing**
             </template>
 
         -   If <result/> matches `OTHER: <text/>`:

package/plugin/skills/ase-help-intent/help.md

@@ -1,7 +1,7 @@
 
 ##  NAME
 
-`ase-help-intent` - Match an Intent to an ASE Command
+`ase-help-intent` - Match an Intent to ASE Commands
 
 ##  SYNOPSIS
 
@@ -14,18 +14,22 @@
 The `ase-help-intent` skill matches a free-text *intent* against the
 *accumulated help* of all ASE skills -- the concatenation of every
 skill's `help.md` file into `skills/ase-help-intent/data.md`, built by
-`npm start build` in `plugin/` -- and generates the *single* best-fitting
-`/ase:ase-xxx-xxx` command that realizes the intent, complete with
-concrete option flags and positional arguments derived from the selected
-skill's `SYNOPSIS`, `OPTIONS`, and `ARGUMENTS`.
-
-The generated command is presented together with a brief rationale in an
-interactive dialog. The dialog lets the user *execute* the command (which
-dispatches the target skill via its generated arguments), *cancel* the
-operation, or *refine* the intent by typing any free-text instruction --
-the instruction is folded into the intent and the best-fitting command is
-re-matched and re-rendered. If no skill confidently matches the intent, a
-warning is emitted and the user is prompted to refine or clarify it.
+`npm start build` in `plugin/` -- and generates *all* adequately fitting
+`/ase:ase-xxx-xxx` commands that realize the intent, ranked best-fitting
+first and limited to the eight best ones. The fit is judged primarily
+against each skill's `SCENARIOS` ("You want ...") and `DESCRIPTION`
+sections, and each command is complete with concrete option flags and
+positional arguments derived from the skill's `SYNOPSIS`, `OPTIONS`,
+and `ARGUMENTS`.
+
+The generated commands are presented together with a brief per-command
+rationale in an interactive dialog. The dialog lets the user *execute*
+one of the commands `C1`...`C8` (which dispatches the target skill via
+its generated arguments), *cancel* the operation, or *refine* the intent
+by typing any free-text instruction -- the instruction is folded into
+the intent and the fitting commands are re-matched and re-rendered. If
+no skill confidently matches the intent, a warning is emitted and the
+user is prompted to refine or clarify it.
 
 The skill exposes *no* option flags beyond `--help`/`-h`; it is driven
 entirely through the intent argument and the interactive dialog.
@@ -34,18 +38,25 @@ entirely through the intent argument and the interactive dialog.
 
 *intent*:
     The free-text intent to be realized. It describes *what* the user
-    wants to achieve; the skill determines *which* ASE skill and *which*
+    wants to achieve; the skill determines *which* ASE skills and *which*
     options and arguments realize it.
 
+##  SCENARIOS
+
+-   You want to know which ASE skills realize what you have in mind
+-   You want free text turned into concrete slash commands with options
+-   You want all matching commands proposed, ranked best-fitting first
+-   You want to refine an intent in a dialog until a command fits
+
 ##  EXAMPLES
 
-Route an intent to the matching command and pick from the dialog:
+Route an intent to the matching commands and pick one from the dialog:
 
 ```text
 ❯ /ase-help-intent lint the TypeScript sources for high-severity issues only
 ```
 
-Route a planning intent to the matching command:
+Route a planning intent to the matching commands:
 
 ```text
 ❯ /ase-help-intent explain how the authentication module works

package/plugin/skills/ase-help-skill/catalog.md

@@ -20,6 +20,9 @@
 ○   `ase-arch-analyze`:    Review Software Architecture
 ○   `ase-arch-discover`:   Discover Components
 
+⎈   **SPECIFICATION**
+○   `ase-spec-edit`:       Edit Specification
+
 ⎈   **CODING**
 ○   `ase-code-analyze`:    Analyze Source Code
 ○   `ase-code-lint`:       Lint Source Code