@rse/ase 1.0.7 → 2.0.0

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

@@ -1,6 +1,6 @@
 ---
 name: ase-spec-edit
-argument-hint: "[--help|-h] [--grill|-g] [--grill-rounds|-r <n>] [--verify|-v] [--worktree|-w] [--loop|-l] [<query>]"
+argument-hint: "[--help|-h] [--approach|-a] [--grill|-g] [--grill-rounds|-r <n>] [--grill-until|-u MUST|SHOULD|MAY] [--grill-perspective|-p <perspective>] [--grill-ground|-G] [--verify|-v] [--worktree|-w <name>[:<branch>]] [--loop|-l] [<query>]"
 description: >
     Edit Specification: Use when the user wants to "edit" the
     SpecBook-based specification (SPEC) in one shot from a query, with
@@ -22,7 +22,7 @@ Edit Specification
 
 <expand name="getopt"
     arg1="ase-spec-edit"
-    arg2="--grill|-g --grill-rounds|-r=1 --verify|-v --worktree|-w --loop|-l">
+    arg2="--approach|-a --grill|-g --grill-rounds|-r=1 --grill-until|-u=(MUST|SHOULD|MAY) --grill-perspective|-p= --grill-ground|-G --verify|-v --worktree|-w= --loop|-l">
     $ARGUMENTS
 </expand>
 
@@ -36,6 +36,8 @@ pruning its statements in one shot -- through the states *querying*,
 @${CLAUDE_SKILL_DIR}/../../meta/ase-format-spec.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-tenets.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-common-grill.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-common-changeset.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-common-approach.md
 
 Procedure
 ---------
@@ -80,6 +82,12 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
         ⧉ **ASE**: ✪ skill: **ase-spec-edit**, ▶ ERROR: invalid `--grill-rounds` value: **<getopt-option-grill-rounds/>**
         </template>
 
+    3.  Resolve a potentially misparsed former boolean `--worktree`
+        option:
+
+        <expand name="changeset-ambiguity"
+            arg1="✪ skill: **ase-spec-edit**"></expand>
+
 2.  **Iterate:**
 
     Perform the states (1) *querying*, (2) *discovering*, (3) *grilling*,
@@ -135,18 +143,50 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
 4.  **State: discovering:**
 
-    1.  Resolve the `SPEC` artifacts by calling the
-        `ase_artifact_list(kind: [ "spec" ])` tool of the `ase` MCP
-        server *once* and reading the returned `artifacts` array of
-        `{ kind, files }` objects to obtain the project-relative file
+    1.  <if condition="<getopt-option-worktree/> is not empty and <worktree-dir/> is empty">
+
+        One *single* worktree serves the whole skill run: it is
+        prepared *once* before the first discovery, so discovering,
+        grilling, and implementing all operate on the *same* tree, and
+        all further `--loop` iterations land in it, too.
+
+        <expand name="changeset-context"
+            arg1="<getopt-option-worktree/>"
+            arg2="✪ skill: **ase-spec-edit**"
+            arg3="true"
+            arg4="true"></expand>
+
+        Set <worktree-dir><context-dir/></worktree-dir>. Do not output
+        anything.
+
+        </if>
+
+    2.  <if condition="<worktree-dir/> is not empty">
+        <expand name="changeset-land" arg1="<worktree-dir/>"></expand>
+        </if>
+
+    3.  Resolve the `SPEC` artifacts to their project-relative file
         list. Do not output anything.
 
-    2.  Read the **SpecBook SCHEMA Model** of the project (resolved as
+        <if condition="<worktree-dir/> is not empty">
+        Run the command `ase artifact list --kind spec` *once* with
+        <worktree-dir/> as its working directory and parse its
+        `- <file/>` output lines into the file list -- the
+        `ase_artifact_list` tool always resolves against the *project*
+        working copy and hence *MUST* *NOT* be used here.
+        </if>
+        <else>
+        Call the `ase_artifact_list(kind: [ "spec" ])` tool of the `ase`
+        MCP server *once* and read the returned `artifacts` array of
+        `{ kind, files }` objects into the file list.
+        </else>
+
+    4.  Read the **SpecBook SCHEMA Model** of the project (resolved as
         described in `ase-format-spec.md`) to learn the allowed object
         kinds, properties, nestings, and value constraints. Do not
         output anything.
 
-    3.  Read all resolved `SPEC` artifacts which are related to
+    5.  Read all resolved `SPEC` artifacts which are related to
         <todo-what/> and <todo-how/>, and check the structure of the
         existing specification -- its artifacts, object kinds, ids,
         properties, descriptions, and `[[xxx]]` references -- to
@@ -161,10 +201,21 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
     1.  Understand what "grilling" is about:
 
-        <expand name="grill-understanding" arg1="the edit query in <todo-what/> and <todo-how/>"></expand>
+        <expand name="grill-understanding"
+            arg1="the edit query in <todo-what/> and <todo-how/>"
+            arg2="<getopt-option-grill-perspective/>"
+            arg3="<getopt-option-grill-ground/>"></expand>
 
-    2.  Perform <getopt-option-grill-rounds/> grilling *rounds*,
-        numbered <m/> (1-<getopt-option-grill-rounds/>).
+    2.  Ground the grilling:
+
+        <expand name="grill-ground"
+            arg1="the edit query in <todo-what/> and <todo-how/>"
+            arg2="<worktree-dir/>"></expand>
+
+    3.  Perform *at most* <getopt-option-grill-rounds/> grilling
+        *rounds*, numbered <m/> (1-<getopt-option-grill-rounds/>) --
+        the round count is a *maximum* only, as every round can
+        *stop* the grilling *early* in its item 2 below.
 
         For each round:
 
@@ -172,7 +223,8 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
             Explicitly start *from scratch* from *only* the current
             <todo-what/> and <todo-how/> and *forget* all information
-            gathered in previous rounds. Set <round-id/> to
+            gathered in previous rounds -- except the grounding facts
+            <grill-facts/>. Set <round-id/> to
             `GRILLING ROUND <m/>/<getopt-option-grill-rounds/>` if
             <getopt-option-grill-rounds/> is greater than 1, or to
             `GRILLING` otherwise (a single round needs no round
@@ -180,82 +232,23 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
         2.  DETERMINE QUESTIONS:
 
-            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*.
-
-            For <question-N-text/> use the format `Shall...?` for
-            questions of focus area `DOMAIN` and `INTERFACE`, the format
-            `Should...?` for questions of focus area `ARCHITECTURE`,
-            and the format `May...?` for questions of focus area
-            `IMPLEMENTATION`.
-
-            In every <question-N-text/>, encode all *literal aspects*
-            -- file paths, artifact ids, object kinds, object ids,
-            property keys, references, and literal values -- with
-            backticks.
-
-            Keep every <question-N-text/> at most *200 characters* long
-            -- compact the text until it fits --, as a longer question
-            overflows its table cell and silently degrades the entire
-            table into a plain text rendering.
-
-        3.  DETERMINE CONTEXT:
-
-            For each question, determine its focus area
-            <context-N-focus/> from the mentioned *Focus Areas*, a 1-3
-            word hint <context-N-topic/>, describing what the question
-            is about, and a <context-N-severity/>, describing how
-            important this question is.
-
-            Set <context-N-id/> to `DOM` for <context-N-focus/> of
-            `DOMAIN`, `IFC` for <context-N-focus/> of `INTERFACE`, `ARC`
-            for <context-N-focus/> of `ARCHITECTURE`, and `IMP` for
-            <context-N-focus/> of `IMPLEMENTATION`.
-
-        4.  SORT QUESTIONS:
-
-            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, 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/>** ▷
-            **<context-N-topic/>**: <question-N-text/>`.
-
-        5.  DETERMINE ANSWERS:
-
-            For all remaining <question-N/>, check the specification and
-            your world knowledge to find *two to three* grounded answer
-            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
-            ` ⚑` to its <answer-N-K-label/>.
-
-            Assemble an <answer-N/> out of `**<answer-N-1-id/>**
-            ▶ **<answer-N-1-label/>**: <answer-N-1-description/>,
-            **<answer-N-2-id/>** ▶ **<answer-N-2-label/>**:
-            <answer-N-2-description/>[, ...]`.
-
-            Keep every assembled <answer-N/> at most *240 characters*
-            long -- drop the least relevant alternative and compact the
-            descriptions until it fits -- as a longer answer overflows
-            its table cell and silently degrades the entire table into a
-            plain text rendering.
-
-        6.  INTERACTIVE DIALOG:
+            <expand name="grill-questions"
+                arg1="<getopt-option-grill-until/>"
+                arg2="✪ skill: **ase-spec-edit**"
+                arg3="file paths, artifact ids, object kinds, object ids, property keys, references, and literal values"
+                arg4="the specification"
+                arg5="">
+                <if condition="<getopt-option-verify/> is not equal `true`">
+                Raise *no* questions at all of focus area `REGRESSION`
+                or `CONFIRMATION`, as without `--verify` no verification
+                takes place which could honor their decisions.
+                </if></expand>
+
+            If <grill-stop/> is `true`, skip the remaining items of
+            this round and all remaining rounds, and continue with
+            the *implementing* state.
+
+        3.  INTERACTIVE DIALOG:
 
             In the following, you *MUST* *NOT* use your built-in
             <user-dialog-tool/> tool! Instead, you *MUST* just show a
@@ -265,8 +258,8 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             `SKIP GRILLING` and `STOP SKILL`, dispatched as follows:
 
             -   If a <result/> is `SKIP GRILLING` or `CANCEL`, ask no
-                further questions, continue with item 7 below (merging
-                the answers gathered so far), and after item 8 skip all
+                further questions, continue with item 4 below (merging
+                the answers gathered so far), and after item 5 skip all
                 remaining rounds and continue with the *implementing*
                 state.
 
@@ -278,54 +271,31 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
                 ⧉ **ASE**: ✪ skill: **ase-spec-edit**, ▶ status: **editing stopped**
                 </template>
 
-            1.  Output only the following <template/> -- it lists *all*
-                questions of the round up-front, one table row per
-                aspect, so the subsequent dialog only has to ask for the
-                combined answer. Align all column edges of the table.
-
-                In every table cell you *MUST* escape each literal pipe
-                character outside a code span as `\|` and you *MUST*
-                open *and* close every backtick code span within the
-                *same* cell -- an unescaped pipe or an unbalanced
-                backtick run splits the cell and silently degrades the
-                entire table into a plain text rendering:
-
-                <template>
-                ⧉ **ASE**: <round-id/>: *Relentless Interviewing Until Clarity*
-
-                | QUESTION      | ANSWERS     |
-                | ------------- | ----------- |
-                | <question-1/> | <answer-1/> |
-                | <question-2/> | <answer-2/> |
-                | [...]         | [...]       |
-
-                Legend: **DOM**: Domain (MUST), **IFC**: Interface (MUST), **ARC**: Architecture (SHOULD), **IMP**: Implementation (MAY)
-                        **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
-                two fixed ones, so the user normally answers all aspects in
-                *one* free-text reply:
+            Show a custom dialog. Its only answer options are the
+            two fixed ones, so the user normally answers all aspects in
+            *one* free-text reply:
 
-                <expand name="custom-dialog" arg1="--other">
-                    <round-id/>: What is your (combined) answer to all (or a subset) of the above questions? (keywords or `Qn:An` references are sufficient)
-                    SKIP GRILLING: skip all remaining grilling and continue with the implementation
-                    STOP SKILL: stop the entire skill immediately
-                </expand>
+            <expand name="custom-dialog" arg1="--other">
+                <round-id/>: What is your (combined) answer to all (or a subset) of the above questions? (keywords or `nX` short responses are sufficient)
+                SKIP GRILLING: skip all remaining grilling and continue with the implementation
+                STOP SKILL: stop the entire skill immediately
+            </expand>
 
-                Dispatch `SKIP GRILLING`, `STOP SKILL`, and `CANCEL` as
-                defined above. Otherwise, strip any leading `OTHER: `
-                prefix from <result/> and treat the remainder as the
-                combined free-text answers to all questions of the
-                round.
+            Dispatch `SKIP GRILLING`, `STOP SKILL`, and `CANCEL` as
+            defined above. Otherwise, strip any leading `OTHER: `
+            prefix from <result/> and treat the remainder as the
+            combined free-text answers to all questions of the
+            round.
 
-        7.  MERGE ANSWERS INTO TODO:
+        4.  MERGE ANSWERS INTO TODO:
 
             Merge all gathered answers in <result/> of the round -- the
             combined reply -- *exclusively* back into <todo-what/> and
             <todo-how/>. Do not output anything.
 
-        8.  SHOW CURRENT TODO:
+            <expand name="grill-short-responses"></expand>
+
+        5.  SHOW UPDATED TODO:
 
             Set <round-suffix/> to
             ` round <m/>/<getopt-option-grill-rounds/>` if
@@ -344,58 +314,28 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
         the following creation and updating of specification content. Do
         not output anything.
 
-    2.  <if condition="<getopt-option-worktree/> is equal `true` and <worktree-dir/> is empty">
-
-        One *single* worktree serves the whole skill run: it is created
-        *once* before the first change set is applied, and all further
-        `--loop` iterations land in it, too.
-
-        1.  Set <worktree-name/> to a unique name, derived from
-            <todo-what/>, which consists of two lower-case words
-            concatenated with a `-` character. Do not output anything.
+    2.  <if condition="<getopt-option-approach/> is equal `true`">
 
-        2.  Determine the *worktree directory* by calling the
-            `ase_worktree_path(id: "<worktree-name/>", create: true)`
-            tool of the `ase` MCP server and capturing its output into
-            <worktree-dir/>. You *MUST* *NEVER* assemble this path
-            yourself. If this tool call fails, only output the following
-            <template/> and then immediately *STOP* processing the
-            entire current skill, leaving the working copy *untouched*:
-
-            <template>
-            ⧉ **ASE**: ✪ skill: **ase-spec-edit**, ▶ ERROR: no Git repository or unsafe worktree directory -- cannot create worktree
-            </template>
-
-        3.  Determine the *existing worktrees* and *existing branches*
-            by running the commands `git worktree list --porcelain` and
-            `git branch --list` (taken exactly as given) and capturing
-            their outputs. If the worktree directory <worktree-dir/> or
-            the branch <worktree-name/> already exists, only output the
-            following <template/> and then immediately *STOP* processing
-            the entire current skill, leaving the existing worktree, its
-            branch, and the working copy *untouched*:
+        Determine the overall approach of the edit, based on
+        <todo-what/> and <todo-how/> plus the information gathered in
+        the *discovering* state:
 
-            <template>
-            ⧉ **ASE**: ✪ skill: **ase-spec-edit**, ▶ ERROR: worktree or branch **<worktree-name/>** already exists
-            </template>
+        <expand name="approach-select"
+            arg1="specification"
+            arg2="✪ skill: **ase-spec-edit**"></expand>
 
-        4.  Create the worktree by running the command
-            `git worktree add "<worktree-dir/>"` (taken exactly as
-            given), which creates the directory *and* -- named after its
-            last path component -- the branch <worktree-name/> from
-            `HEAD`. If this command fails, only output the following
-            <template/> and then immediately *STOP* processing the
-            entire current skill, leaving the working copy *untouched*:
+        If <chosen-approach/> is empty, only output the following <template/>
+        and then immediately *STOP* processing the entire current skill:
 
-            <template>
-            ⧉ **ASE**: ✪ skill: **ase-spec-edit**, ▶ ERROR: worktree **<worktree-name/>** failed to create
-            </template>
+        <template>
+        ⧉ **ASE**: ✪ skill: **ase-spec-edit**, ▶ status: **editing stopped**
+        </template>
 
-        5.  Only output the following <template/>:
+        Otherwise, merge <chosen-approach/> *exclusively* into <todo-how/>,
+        where the chosen approach overrides any conflicting
+        implementation detail, and expand the following:
 
-            <template>
-            ⧉ **ASE**: ✪ skill: **ase-spec-edit**, ◉ worktree: **.ase/worktree/<worktree-name/>**, ▶ status: **worktree created**
-            </template>
+        <expand name="todo-box" arg1="current state (after approaching)"></expand>
 
         </if>
 
@@ -427,13 +367,7 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
         there, too.
 
         <if condition="<worktree-dir/> is not empty">
-        The change set *MUST* land *exclusively inside* the worktree
-        <worktree-dir/>: resolve *every* file path relative to
-        <worktree-dir/> instead of the original working copy. You *MUST*
-        *NEVER* modify, stage, stash, revert, or commit anything
-        *outside* of this worktree. Leave the worktree *uncommitted*:
-        do *not* run `git add` and do *not* run `git commit`, so the
-        user keeps full control over the final commit.
+        <expand name="changeset-land" arg1="<worktree-dir/>"></expand>
         </if>
 
     5.  Output only the following <template/>. You *MUST* *NOT* output a

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

@@ -7,10 +7,14 @@
 
 `ase-spec-edit`
     [`--help`|`-h`]
+    [`--approach`|`-a`]
     [`--grill`|`-g`]
     [`--grill-rounds`|`-r` *n*]
+    [`--grill-until`|`-u` `MUST`|`SHOULD`|`MAY`]
+    [`--grill-perspective`|`-p` *perspective*]
+    [`--grill-ground`|`-G`]
     [`--verify`|`-v`]
-    [`--worktree`|`-w`]
+    [`--worktree`|`-w` *name*[`:`*branch*]]
     [`--loop`|`-l`]
     [*query*]
 
@@ -31,11 +35,12 @@ WHAT and its implementation-detail HOW parts), *discovering* (resolve
 the `SPEC` artifacts, read the *SpecBook* schema configuration of the
 project, and read the specification artifacts related to the query),
 *grilling* (optionally stress-test the query with rounds of questions),
-*implementing* (apply the change set in place, honoring the GENERIC and
-SPECIFYING tenets and the `SPEC` format contract), and *verifying*
-(optionally validate the specification until it passes). The *querying*
-state and every *grilling* round close with an `EDIT TODO` box showing
-the established `WHAT` and `HOW` information.
+*implementing* (optionally select an approach, then apply the change set
+in place, honoring the GENERIC and SPECIFYING tenets and the `SPEC`
+format contract), and *verifying* (optionally validate the specification
+until it passes). The *querying* state, every *grilling* round, and the
+approach selection close with an `EDIT TODO` box showing the established
+`WHAT` and `HOW` information.
 
 The change set stays strictly restricted to the `SPEC` artifacts -- the
 artifact kinds `CODE`, `DOCS`, `TASK`, `INFR`, and `OTHR` are never
@@ -45,6 +50,15 @@ timestamp refreshed.
 
 ##  OPTIONS
 
+-   `--approach`|`-a`:
+    Before applying the change set, propose one or more specification
+    approaches with pros and cons, recommend one of them, and let the
+    user pick the preferred one via an interactive dialog (or, under the
+    `black` project boxing or in headless mode, automatically pick the
+    recommended one). The chosen approach is merged into the HOW part of
+    the query. Without `--approach`, no approaches are determined at
+    all.
+
 -   `--grill`|`-g`:
     Grill the query before implementing, similar to `ase-task-grill`:
     raise 1-10 questions per round which resolve the open points of the
@@ -52,11 +66,16 @@ timestamp refreshed.
     (domain-specifics, must be clarified), `INTERFACE` (externally
     observable behavior or UI/API interfaces, must be clarified),
     `ARCHITECTURE` (structure, wiring, placement, or dependencies,
-    should be clarified), or `IMPLEMENTATION` (inner technical details,
-    can be clarified) -- and a 1-3 word `TOPIC` hint. The questions of a
-    round are sorted by descending focus area importance (`DOMAIN`,
-    `INTERFACE`, `ARCHITECTURE`, `IMPLEMENTATION`) and are announced
-    together below a `GRILLING ROUND K/L` line (the round numbering is
+    should be clarified), `IMPLEMENTATION` (inner technical details,
+    can be clarified), `REGRESSION` (what must not break, should be
+    clarified), or `CONFIRMATION` (what proves the specified behavior,
+    should be clarified) -- and a 1-3 word `TOPIC` hint. The questions
+    of a round are sorted by descending focus area importance
+    (`DOMAIN`, `INTERFACE`, `ARCHITECTURE`, `IMPLEMENTATION`,
+    `REGRESSION`, `CONFIRMATION`). Questions of focus area
+    `REGRESSION` and `CONFIRMATION` are raised only together with
+    `--verify`, as only then a verification honors their decisions.
+    All questions of a round are announced together below a `GRILLING ROUND K/L` line (the round numbering is
     omitted when only a single round is performed) as a
     `QUESTION`/`ANSWERS` table with one row per question, each row
     carrying two to three grounded answer alternatives (with the
@@ -65,15 +84,54 @@ timestamp refreshed.
     whose question asks for the combined answer to all (or a subset) of
     the listed questions and whose only answer options are the fixed
     `SKIP GRILLING` (skip the remaining grilling) and `STOP SKILL` (stop
-    the skill) ones, plus free-text input. The answers are merged back
-    into the WHAT and HOW parts of the query. Without `--grill`, no
-    questions are asked at all.
+    the skill) ones, plus free-text input. The questions are numbered
+    `1`, `2`, etc. and their answer alternatives are lettered `A`, `B`,
+    etc., so the free-text input can cherry-pick answers with short
+    responses matching `\d+[a-zA-Z]` (like `1A 2c`), freely mixed with
+    keyword text. The answers are merged back into the WHAT and HOW
+    parts of the query. Without `--grill`, no questions are asked at
+    all.
 
 -   `--grill-rounds`|`-r` *n*:
-    The number of grill rounds to apply (default: `1`). Each round
-    starts from scratch from only the current WHAT and HOW parts,
+    The *maximum* number of grill rounds to apply (default: `1`). Each
+    round starts from scratch from only the current WHAT and HOW parts,
     forgetting all information of previous rounds, and closes with an
-    `EDIT TODO` box. Only effective together with `--grill`.
+    `EDIT TODO` box. The grilling stops early -- announced by a
+    `grilling finished early` status line -- once a round, even the
+    first one, finds the open points clear enough according to
+    `--grill-until`. Only effective together with `--grill`.
+
+-   `--grill-until`|`-u` `MUST`|`SHOULD`|`MAY`:
+    Grill until at least all open points of the given severity or
+    higher are clear (default: `MUST`), where the severity follows from
+    the focus area: `MUST` (`DOMAIN`, `INTERFACE`), `SHOULD`
+    (`ARCHITECTURE`, `REGRESSION`, `CONFIRMATION`), and `MAY`
+    (`IMPLEMENTATION`). Independent of this, every open point is rated
+    with an individual impact (`HIGH`, `MEDIUM`, or `LOW`), which
+    decides which points are raised as questions and in which order
+    within a focus area. Only effective together with `--grill`.
+
+-   `--grill-perspective`|`-p` *perspective*:
+    Grill exclusively from the logical *perspective* -- a keyword or
+    short hint like `domain`, `performance`, or `security`. The
+    perspective acts as an exclusive lens: only open points relevant from
+    this perspective are raised as questions, while every question still
+    carries its focus area, severity, and impact. The active perspective
+    is shown in the announcement line, like `GRILLING (security)`.
+    Without a perspective, the grilling is holistic. Only effective together with `--grill`.
+
+-   `--grill-ground`|`-G`:
+    Ground the grilling in facts instead of the world knowledge of the
+    model alone: once before the first round, the artifacts of all kinds
+    (`SPEC`, `CODE`, `DOCS`, `INFR`, and `OTHR`) are scanned for
+    the project facts relevant to the grilled subject (from the given
+    perspective, if any) and the Internet/Web is searched for the
+    established practices, standards, patterns, and pitfalls about it.
+    These facts serve all rounds, both for raising the questions and for
+    preferably deriving their answer alternatives. The grounding is shown
+    in the announcement line, like `GRILLING (security, grounded)`. If
+    no usable facts are found, a warning is shown and the grilling falls
+    back to model knowledge. Only effective together with `--grill`.
 
 -   `--verify`|`-v`:
     Verify the edited specification by validating it via *SpecBook*
@@ -82,14 +140,22 @@ timestamp refreshed.
     the last round are listed as `REMAINING DIAGNOSTICS`. Without
     `--verify`, strictly no validation is performed at all.
 
--   `--worktree`|`-w`:
-    Apply the change sets inside a dedicated Git worktree (as
-    `ase-task-implement --worktree`) instead of the current working
-    copy. One single worktree, named by a two-word id derived from the
-    first query, serves the whole skill run: all `--loop` iterations
-    land in it and it is left uncommitted for review. Under `--verify`,
-    the validation then runs as the `ase spec lint` command inside the
-    worktree.
+-   `--worktree`|`-w` *name*[`:`*branch*]:
+    Apply the change sets inside the dedicated Git worktree
+    `.ase/worktree/<name>` instead of the current working copy. The
+    worktree is *reused* if it already exists -- then switched to
+    *branch* if given and it has no uncommitted changes --, otherwise
+    it is *created* with the branch *branch* (default: *name*),
+    checked out if it exists or created from `HEAD` otherwise. One
+    single worktree serves the whole skill run: it is prepared before
+    the first discovery, so discovering, grilling, and implementing all
+    operate on it, all `--loop` iterations land in it, and it is left
+    uncommitted for review. Under
+    `--verify`, the validation then runs as the `ase spec lint` command
+    inside the worktree. If *name* is a bare lower-case word naming no
+    existing worktree and a *query* follows (like `-w fix the crash`, a
+    former boolean `-w` usage), the skill asks whether *name* is the
+    worktree name or the first query word.
 
 -   `--loop`|`-l`:
     Loop the whole state cycle: after each iteration, ask for the next
@@ -110,6 +176,7 @@ timestamp refreshed.
 -   You want `SPEC` changes without the task plan ceremony
 -   You want the query stress-tested by grilling before the spec is edited
 -   You want specification edits validated by SpecBook linting
+-   You want the change set to land on a specific Git branch or worktree
 
 ##  EXAMPLES
 
@@ -125,10 +192,24 @@ Grill the query with two rounds first, then edit and validate:
 ❯ /ase-spec-edit -g -r 2 -v split the Event entity into Event and EventSeries
 ```
 
+Let the user pick one of several specification approaches first, then
+edit:
+
+```text
+❯ /ase-spec-edit -a model the access permissions of the personas
+```
+
+Grill the query exclusively from the domain perspective, grounded in
+the project artifacts and the Internet/Web, then edit:
+
+```text
+❯ /ase-spec-edit -g -p domain -G add recurring events to the Event model
+```
+
 Loop over multiple specification edits inside a dedicated Git worktree:
 
 ```text
-❯ /ase-spec-edit -l -w
+❯ /ase-spec-edit -l -w event-series
 ```
 
 ##  SEE ALSO

package/plugin/skills/ase-sync-reconcile/help.md

@@ -134,5 +134,5 @@ specification as a unified diff, without applying it:
 
 ##  SEE ALSO
 
-[`ase-meta-changelog`](../ase-meta-changelog/help.md),
+[`ase-repo-changelog`](../ase-repo-changelog/help.md),
 [`ase-task-implement`](../ase-task-implement/help.md).