@rse/ase 0.9.60 → 0.9.62

package/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.60",
+    "version":                              "0.9.62",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.60",
+    "version":     "0.9.62",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.60",
+    "version":     "0.9.62",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.github/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.60",
+    "version":     "0.9.62",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/agents/ase-code-lint.md

@@ -15,7 +15,7 @@ Workflow
 1.  Set the requested context: <context>$ARGUMENTS</context>.
     The *first* whitespace-separated token of <context/> is the
     comma-separated *aspect set* <aspects/> (a non-empty subset of the
-    aspect ids `A01`...`A20`). The *remaining* tokens are the source
+    aspect ids `A01`...`A21`). The *remaining* tokens are the source
     code files to check.
 
 2.  Use the `Read` tool to read all source code files referenced by
@@ -28,7 +28,7 @@ Workflow
 
 4.  Set <problems/> to empty.
     Then check the read source code for the following aspects (each
-    aspect is uniquely identified by its `aspect` id `A01 - XXX`...`A20
+    aspect is uniquely identified by its `aspect` id `A01 - XXX`...`A21
     - XXX`), but *strictly limited* to those aspects whose id is
     contained in the aspect set <aspects/> -- all other aspects are
     *not* checked and their problems are *never* reported:
@@ -266,6 +266,50 @@ Workflow
         *masks* another bug (e.g., unreachable code after a misplaced
         `return` that skips cleanup logic).
 
+    -   **A21 - DOCUMENTATION**:
+        Check for *incomplete* and for *excessive* code documentation
+        across the following sub-aspects. The yardstick is a *minimal*
+        description: one or two lines stating WHAT the construct does,
+        optimally written in the *idiomatic documentation convention* of
+        the project or the target programming language.
+
+        -   **C1 MISSING-DOCUMENTATION**: functions, methods, classes,
+            interfaces, or modules without any documentation comment
+            describing their purpose -- *private* and *internal*
+            constructs included, not just the public API surface.
+            Exclude trivial constructs whose name already fully conveys
+            the purpose (plain getters/setters, one-line lambdas,
+            delegating overloads) and constructs inheriting the
+            documentation of an overridden or implemented declaration.
+            Propose *adding* those missing comments.
+
+        -   **C2 EXCESSIVE-DOCUMENTATION**: comments going far beyond
+            the minimal description: narrated decision logs ("chose X
+            over Y because ..."), change history ("now uses X instead of
+            Y"), line-by-line explanations of the obvious, or comment
+            blocks substantially longer than the code they describe.
+            Propose *condensing* to a brief 1-2 line description (up to
+            4 lines only for genuinely non-obvious constraints).
+
+        -   **C3 RESTATING-DOCUMENTATION**: comments merely repeating
+            the code or the identifier verbatim without adding any
+            information (e.g., "increment i" above `i++`). Propose
+            *removing* them.
+
+        -   **C4 DRIFTED-DOCUMENTATION**: comments contradicting the
+            code they describe (stale parameter lists, outdated behavior
+            claims). Propose *correcting* the *comment* only -- *never*
+            change the code under this aspect.
+
+        Keep intact comments stating a *constraint the code cannot
+        show* (brief WHY-comments on non-obvious decisions) -- they are
+        neither excessive nor restating.
+
+        Severity guidance: C1 defaults to MEDIUM for non-trivial
+        constructs, else LOW; C2 and C3 default to LOW, escalating to
+        MEDIUM when the noise dominates the file; and C4 defaults to
+        MEDIUM (it actively misleads).
+
     Be conservative - only report clear, well-grounded issues
     that require an actual *code change*. Think twice to avoid
     *false positives*.
@@ -277,7 +321,7 @@ Workflow
 
     For *each* found problem which requires a code change:
 
-    1.  Set <aspect/> to the identifier `A01 - XXX`...`A20 - XXX`,
+    1.  Set <aspect/> to the identifier `A01 - XXX`...`A21 - XXX`,
         indicating the aspect under which the problem was detected.
 
     2.  Set <severity/> to the string `LOW`, `MEDIUM`, or `HIGH`,

package/plugin/meta/ase-common-grill.md

@@ -0,0 +1,89 @@
+
+Grill Skill Common Steps
+========================
+
+<define name="grill-understanding">
+
+-   GOAL:
+
+    Interactively interviewing the user *relentlessly* about every
+    *essential aspect* of <arg1/> *until* reaching a shared
+    understanding and no major decisions/questions are left open.
+
+    This especially means that you *MUST* clarify as many aspects as
+    necessary to ensure that for at least the most important decisions,
+    during a subsequent implementation, no essential freedom of choice
+    exists any longer.
+
+-   FOCUS:
+
+    Focusing on the following outside-in *Focus Areas*, in order of
+    descending importance for the grilling operation:
+
+    1.  *DOMAIN*: Aspects affecting domain-specifics. These
+        aspects *MUST* be clarified, as they are about
+        the "what" of the solution and they
+        non-technically shape the solution noticeably.
+
+    2.  *INTERFACE*: Aspects affecting externally observable
+        behavior or interfaces, especially aspects about user (UI)
+        and machine (API) interfaces. These aspects *MUST* be
+        clarified, as they are externally visible and
+        shape the boundary of the solution.
+
+    3.  *ARCHITECTURE*: Aspects affecting software and system
+        architecture, especially decisions on structure, wiring,
+        placement, or dependencies. These aspects *SHOULD*
+        be clarified, as they technically shape the solution noticeably.
+
+    4.  *IMPLEMENTATION*: Aspects affecting any other
+        implementation details, especially how <arg1/>
+        is realized in the code base. These aspects *CAN* be
+        clarified, as they shape technical inner details only.
+
+-   SEVERITY:
+
+    The *Focus Area* indicate the severity of the aspect:
+
+    -   severity *MUST*   for *DOMAIN*         focus area
+    -   severity *MUST*   for *INTERFACE*      focus area
+    -   severity *SHOULD* for *ARCHITECTURE*   focus area
+    -   severity *MAY*    for *IMPLEMENTATION* focus area
+
+-   INDICATORS:
+
+    Check the following indicators for identifying problematic
+    aspects:
+
+    -   *Fuzzy Language*:
+        When the user uses vague or overloaded terms instead of
+        a precise or canonical term.
+
+    -   *Conflicting Terminology*:
+        When the user uses a term that conflicts with the
+        existing terminology in the code base.
+
+    -   *Conflicting Code*:
+        When the user states how something works, check whether the
+        current code state really agrees.
+
+    -   *Non-Concrete Scenarios*:
+        When domain relationships are being discussed,
+        stress-test them with specific scenarios. Theoretically
+        invent realistic scenarios that probe edge cases and
+        force the user to be precise about the boundaries
+        between concepts.
+
+    -   *Unspecified Architecture Patterns*:
+        When the realization of the functionality is known to
+        be reasonably realizable with more than one decent
+        architecture pattern, but no such pattern was
+        mentioned.
+
+    -   *Unspecified Dependencies*:
+        When the realization of functionality usually is known
+        to be supported by the use of frameworks or libraries,
+        but no dependencies on such solutions were mentioned.
+
+</define>
+

package/plugin/meta/ase-dialog.md

@@ -36,6 +36,12 @@ following procedure:
     description. The second and following lines each provide an
     answer label and an answer description.
 
+    Parse the first line by splitting it at its *first* `: ` into
+    <question-label/> (the text before) and <question-description/>
+    (the remaining text, *without* the label). The label is rendered
+    *only* as the box subtitle below, so <question-description/>
+    *MUST* *NOT* repeat it.
+
     Do not output anything in this step!
 
 2.  Render the custom dialog, collect the user input, and dispatch on the result:

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.60",
+    "version":                              "0.9.62",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

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

@@ -482,7 +482,7 @@ interface quality, quality attributes, and architecture governance.
     nothing and hence emit no output at all):
 
     <ase-tpl-hint level="minimal">
-    For deeper analysis, suggestions on solution approaches and then final source code changes, use `/ase-code-resolve <id-prefix/>P{n}` or `/ase-code-resolve <id-prefix/>T{n}` in the same or even a different session.
+    For deeper analysis, suggestions on solution approaches and then final source code changes, use `/ase-code-resolve <id-prefix/>P{n}` or `/ase-code-resolve <id-prefix/>T{n}`, or for a direct one-shot fix use `/ase-code-edit <id-prefix/>P{n}` or `/ase-code-edit <id-prefix/>T{n}`, in the same or even a different session.
     </ase-tpl-hint>
 
     </step>

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

@@ -218,7 +218,7 @@ problems in *performance* and *efficiency*, or problems in *security*.
     nothing and hence emit no output at all):
 
     <ase-tpl-hint level="minimal">
-    For deeper analysis, suggestions on solution approaches and then final problem resolution, use `/ase-code-resolve <id-prefix/>P{n}` in the same or even a different session.
+    For deeper analysis, suggestions on solution approaches and then final problem resolution, use `/ase-code-resolve <id-prefix/>P{n}`, or for a direct one-shot fix use `/ase-code-edit <id-prefix/>P{n}`, in the same or even a different session.
     </ase-tpl-hint>
 
     You *MUST* not output anything else in this STEP 3,

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

@@ -52,7 +52,8 @@ problem as a `PROBLEM` entry with severity (`LOW`, `MEDIUM`, `HIGH`) and
 inline file/line references (in the performance lens, each entry
 additionally carries an *evidence* and a *trade-off* line), and persists
 results in the `ase` MCP key/value store as `ase-issue-P<n>` entries so
-they can later be resolved via `ase-code-resolve P<n>`.
+they can later be resolved via `ase-code-resolve P<n>` or directly
+fixed via `ase-code-edit P<n>`.
 
 ##  ARGUMENTS
 

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

@@ -1,11 +1,11 @@
 ---
 name: ase-code-edit
-argument-hint: "[--help|-h] [--mode|-m auto|craft|refactor|resolve] [--grill|-g] [--grill-rounds|-r <n>] [--verify|-v] [--worktree|-w] [--loop|-l] [<query>]"
+argument-hint: "[--help|-h] [--mode|-m auto|craft|refactor|resolve] [--grill|-g] [--grill-rounds|-r <n>] [--verify|-v] [--worktree|-w] [--loop|-l] [<query>|<issue-id>]"
 description: >
     Edit Source Code: Use when the user wants to "edit" the code base in
-    one shot from a query, fusing crafting, refactoring, and resolving
-    with optional grilling, verification, looping, and Git worktree
-    isolation.
+    one shot from a query or a bare analyzer issue id like "P1", fusing
+    crafting, refactoring, and resolving with optional grilling,
+    verification, looping, and Git worktree isolation.
 user-invocable: true
 disable-model-invocation: false
 effort: xhigh
@@ -33,6 +33,7 @@ resolving in one shot -- through the states *querying*, *discovering*,
 </objective>
 
 @${CLAUDE_SKILL_DIR}/../../meta/ase-tenets.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-common-grill.md
 
 Procedure
 ---------
@@ -50,12 +51,13 @@ which shows the established <todo-what/> and <todo-how/>, where a still
 empty <todo-what/> or <todo-how/> renders as `(none)`:
 
 <template>
-<ase-tpl-boxed title="EDIT TODO" subtitle="<arg1/>">
+<ase-tpl-head title="EDIT TODO" subtitle="<arg1/>"/>
 
 **WHAT**: <todo-what/>
+
 **HOW**:  <todo-how/>
 
-</ase-tpl-boxed>
+<ase-tpl-foot title="EDIT TODO" subtitle="<arg1/>"/>
 </template>
 
 </define>
@@ -113,7 +115,32 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
         </if>
 
-    2.  Convert the <query/> *fresh* into <todo-what/> -- the
+    2.  <if condition="<query/> matches the regexp `^([a-zA-Z][a-zA-Z0-9_]*-)?[PT]\d+$`">
+
+        The <query/> is a bare issue identifier (like `P1`, `T1`, or
+        `<prefix>-P1`) previously produced by `ase-code-analyze` or
+        `ase-arch-analyze`. Set <issue-id><query/></issue-id> and call
+        the `ase_kv_get(key: "ase-issue-<issue-id/>")` tool of the
+        `ase` MCP server to retrieve the persisted problem description.
+        If the returned `text` is non-empty, set <query><text/></query>
+        and only output the following <template/>:
+
+        <template>
+        ⧉ **ASE**: ✪ skill: **ase-code-edit**, ⇌ issue: **<issue-id/>**, ▶ status: **issue retrieved**
+        </template>
+
+        Otherwise, set <issue-id></issue-id> (empty) and only output the
+        following <template/>, then, under `--loop`, continue with the
+        *next* iteration at item 3.1 above, or, without `--loop`,
+        immediately *STOP* processing the entire current skill:
+
+        <template>
+        ⧉ **ASE**: ✪ skill: **ase-code-edit**, ▶ ERROR: no analyzer result exists for issue **<query/>**
+        </template>
+
+        </if>
+
+    3.  Convert the <query/> *fresh* into <todo-what/> -- the
         domain-specific, non-implementation-detail information -- and
         <todo-how/> -- the remaining information -- discarding all
         <todo-what/>/<todo-how/> content of any previous iteration.
@@ -121,11 +148,11 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
         and during later implementation just interpret the query best-effort.
         Do not output anything.
 
-    3.  Expand the following:
+    4.  Expand the following:
 
         <expand name="todo-box" arg1="current state (after querying)"></expand>
 
-    4.  Set <query></query> (clear the query, so every further `--loop`
+    5.  Set <query></query> (clear the query, so every further `--loop`
         iteration asks for a fresh one). Do not output anything.
 
 4.  **State: discovering:**
@@ -143,85 +170,16 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
     1.  Understand what "grilling" is about:
 
-        -   GOAL:
-
-            Interactively interviewing the user *relentlessly* about every
-            *essential aspect* of the edit query in <todo-what/> and
-            <todo-how/> *until* reaching a shared understanding and no
-            major decisions/questions are left open.
-
-            This especially means that you *MUST* clarify as many aspects as
-            necessary to ensure that for at least the most important decisions,
-            during a subsequent implementation, no essential freedom of choice
-            exists any longer.
-
-        -   FOCUS:
-
-            Focusing on the following outside-in *Focus Areas*, in order of
-            descending importance for the grilling operation:
-
-            1.  *DOMAIN*: Aspects affecting domain-specifics. These
-                aspects *MUST* be clarified, as they are about
-                the "what" of the solution and they
-                non-technically shape the solution noticeably.
-
-            2.  *INTERFACE*: Aspects affecting externally observable
-                behavior or interfaces, especially aspects about user (UI)
-                and machine (API) interfaces. These aspects *MUST* be
-                clarified, as they are externally visible and
-                shape the boundary of the solution.
-
-            3.  *ARCHITECTURE*: Aspects affecting software and system
-                architecture, especially decisions on structure, wiring,
-                placement, or dependencies. These aspects *SHOULD*
-                be clarified, as they technically shape the solution noticeably.
-
-            4.  *IMPLEMENTATION*: Aspects affecting any other
-                implementation details, especially how the edit query
-                is realized in the code base. These aspects *CAN* be
-                clarified, as they shape technical inner details only.
-
-        -   INDICATORS:
-
-            Check the following indicators for identifying problematic
-            aspects:
-
-            -   *Fuzzy Language*:
-                When the user uses vague or overloaded terms instead of
-                a precise or canonical term.
-
-            -   *Conflicting Terminology*:
-                When the user uses a term that conflicts with the
-                existing terminology in the code base.
-
-            -   *Conflicting Code*:
-                When the user states how something works, check whether the
-                current code state really agrees.
-
-            -   *Non-Concrete Scenarios*:
-                When domain relationships are being discussed,
-                stress-test them with specific scenarios. Theoretically
-                invent realistic scenarios that probe edge cases and
-                force the user to be precise about the boundaries
-                between concepts.
-
-            -   *Unspecified Architecture Patterns*:
-                When the realization of the functionality is known to
-                be reasonably realizable with more than one decent
-                architecture pattern, but no such pattern was
-                mentioned.
-
-            -   *Unspecified Dependencies*:
-                When the realization of functionality usually is known
-                to be supported by the use of frameworks or libraries,
-                but no dependencies on such solutions were mentioned.
+        <expand name="grill-understanding" arg1="the edit query in <todo-what/> and <todo-how/>"></expand>
 
     2.  Perform <getopt-option-grill-rounds/> grilling *rounds*,
         numbered <m/> (1-<getopt-option-grill-rounds/>).
 
         For each round:
 
-        1.  Explicitly start *from scratch* from *only* the current
+        1.  INITIALIZE TODO:
+
+            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
             `GRILLING ROUND <m/>/<getopt-option-grill-rounds/>` if
@@ -229,46 +187,81 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             `GRILLING` otherwise (a single round needs no round
             numbering). Do not output anything.
 
-        2.  Determine the questions <question-N/>, chosen to
+        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
             resolve the open points related to the above understanding
             of grilling, by focusing on the mentioned *Focus Areas*.
 
-            For each <question-N/> determine its <focus-area-N/> and a
-            <topic-N/>, a 1-2 word hint describing what the question is
-            about. Render <focus-area-N/> in the tables below as
-            `**DOMAIN** (MUST)`, `**INTERFACE** (MUST)`,
-            `**ARCHITECTURE** (SHOULD)`, or `**IMPLEMENTATION** (MAY)`
-            correspondingly.
-
-            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/>, encode all *literal aspects* -- file
-            and directory paths, identifiers, symbols, types, commands,
-            options, configuration keys, and literal values -- with
-            backticks.
-
-        3.  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.
-
-        4.  For all remaining <question-N/>, check the code base
-            and your world knowledge to find *two to four*
-            grounded answer alternatives <answer-N-K/> with a
-            brief label <answer-N-K-label/> and a description
-            <answer-N-K-description/> which reflects the current
-            <todo-what/>/<todo-how/> understanding by prefixing its
-            description with `✻ **CURRENT** ✻`. Assemble a <answer-N/>
-            out of `**<answer-N-1-label/>**: <answer-N-1-description/> ─◇─
-            **<answer-N-2-label/>**: <answer-N-2-description/> ─◇─ [...]`.
-
-        5.  In the following, you *MUST* *NOT* use your built-in
+            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 and directory paths, identifiers, symbols, types,
+            commands, options, configuration keys, 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. 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 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
+            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:
+
+            In the following, you *MUST* *NOT* use your built-in
             <user-dialog-tool/> tool! Instead, you *MUST* just show a
             custom dialog according to the expanded `custom-dialog`
             definition. You *MUST* closely follow this definition. The
@@ -276,8 +269,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 6 below (merging
-                the answers gathered so far), and after item 7 skip all
+                further questions, continue with item 7 below (merging
+                the answers gathered so far), and after item 8 skip all
                 remaining rounds and continue with the *implementing*
                 state.
 
@@ -292,18 +285,26 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             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. If
-                <getopt-option-grill-rounds/> is equal `1`, *omit* the
-                leading `<round-id/>` line:
+                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/>:
+                ⧉ **ASE**: <round-id/>: *Relentless Interviewing Until Clarity*
+
+                | QUESTION      | ANSWERS     |
+                | ------------- | ----------- |
+                | <question-1/> | <answer-1/> |
+                | <question-2/> | <answer-2/> |
+                | [...]         | [...]       |
 
-                | ASPECT   | FOCUS AREA      | TOPIC       | **QUESTION** ┈─▶ **ANSWERS**      |
-                | -------- | --------------- | ----------- | --------------------------------- |
-                | 1/<n/>   | <focus-area-1/> | <topic-1/>  | **<question-1/>** ┈─▶ <answer-1/> |
-                | 2/<n/>   | <focus-area-2/> | <topic-2/>  | **<question-2/>** ┈─▶ <answer-2/> |
-                | [...]    | [...]           | [...]       | [...]                             |
+                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
                 </template>
 
             2.  Show a custom dialog. Its only answer options are the
@@ -311,7 +312,7 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
                 *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 are sufficient)
+                    <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>
@@ -322,11 +323,15 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
                 combined free-text answers to all questions of the
                 round.
 
-        6.  Merge all gathered answers of the round -- the combined
-            reply -- *exclusively* back into <todo-what/> and
+        7.  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.
 
-        7.  Set <round-suffix/> to
+        8.  SHOW CURRENT TODO:
+
+            Set <round-suffix/> to
             ` round <m/>/<getopt-option-grill-rounds/>` if
             <getopt-option-grill-rounds/> is greater than 1, or to
             empty otherwise, and expand the following -- this
@@ -343,6 +348,10 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             `resolve`: Set <task-kind/> to `CRAFTING`, `REFACTORING`,
             or `RESOLVING` correspondingly.
 
+        -   Else if <issue-id/> is not empty (`auto` with a retrieved
+            analyzer issue): Set <task-kind/> to `RESOLVING`, as the
+            edit fixes a reported problem.
+
         -   Else (`auto`): *Infer* the <task-kind/> from <todo-what/> and
             <todo-how/>: set to `RESOLVING` if the edit predominantly
             fixes a defect, set to `REFACTORING` if it predominantly
@@ -427,7 +436,15 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
         user keeps full control over the final commit.
         </if>
 
-    4.  Output only the following <template/>. You *MUST* *NOT* output a
+    4.  <if condition="<issue-id/> is not empty">
+        Call the `ase_kv_delete(key: "ase-issue-<issue-id/>")` tool of
+        the `ase` MCP server to remove the now-resolved analyzer result
+        from the key/value store, then set <issue-id></issue-id> (empty),
+        so every further `--loop` iteration starts without an issue.
+        Do not output anything.
+        </if>
+
+    5.  Output only the following <template/>. You *MUST* *NOT* output a
         change summary, a list of modified artifacts, a rationale, or a
         unified diff of the changes -- *independent* of
         <ase-project-boxing/>, whose exposure rules are explicitly
@@ -447,7 +464,7 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
     1.  Verify whether the implementation fulfills <todo-what/> and
         <todo-how/> by running available verification commands
         (build, tests, linter, type-checker)
-        <if condition=" <worktree-dir/> is not empty">
+        <if condition="<worktree-dir/> is not empty">
         , each with <worktree-dir/> as its working directory
         </if>.
 

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

@@ -55,7 +55,7 @@ implementation until it passes). The *querying* state and every
     All questions of a round are announced together below a
     `GRILLING ROUND K/L` line (the announcement line and round numbering
     are omitted when only a single round is performed) as an
-    `ASPECT`/`FOCUS AREA`/`TOPIC`/`QUESTION` table with one row per
+    `#`/`FOCUS ▶ TOPIC`/`QUESTION` table with one row per
     question, each row carrying two to four grounded answer alternatives
     (with the alternative reflecting the current understanding marked as
     `CURRENT`). They are then asked in *one* batch via a single

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

@@ -20,7 +20,7 @@ Lint Source Code
 
 <expand name="getopt"
     arg1="ase-code-lint"
-    arg2="--auto|-a --severity|-S=(LOW|MEDIUM|HIGH) --include|-i=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20)... --exclude|-e=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20)...">
+    arg2="--auto|-a --severity|-S=(LOW|MEDIUM|HIGH) --include|-i=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20|A21)... --exclude|-e=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20|A21)...">
     $ARGUMENTS
 </expand>
 
@@ -53,16 +53,16 @@ related to a set of code quality aspects.
     <getopt-option-include/> and <getopt-option-exclude/> as
     comma-separated token lists, silently dropping the `none` sentinel
     and any empty token. If a token <token/> is *not* one of the aspect
-    ids `A01`...`A20`, only output the following <template/> and then
+    ids `A01`...`A21`, only output the following <template/> and then
     *STOP* the entire flow (do not perform any further steps):
 
     <template>
     ⧉ **ASE**: ✪ skill: **ase-code-lint**, ▶ ERROR: invalid aspect id: **<token/>**
     </template>
 
-    Otherwise set <aspects/> to *all* twenty aspect ids `A01`...`A20`
+    Otherwise set <aspects/> to *all* twenty-one aspect ids `A01`...`A21`
     if both lists are empty, to the *include* list if only it is
-    non-empty, to all twenty *minus* the *exclude* list if only it is
+    non-empty, to all twenty-one *minus* the *exclude* list if only it is
     non-empty, and to the *include* list *minus* the *exclude* list if
     both are non-empty. If the resulting <aspects/> is *empty*, only
     output the following <template/> and then *STOP* the entire flow
@@ -143,7 +143,7 @@ related to a set of code quality aspects.
 
     Use the following <template/> to output a summary of the detected
     problems in <problems/> (if any were found), in the original aspect
-    ordering `A01 - XXX`...`A20 - XXX`.
+    ordering `A01 - XXX`...`A21 - XXX`.
 
     <template>
     <ase-tpl-bullet-secondary/> **LINT SUMMARY**:

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

@@ -27,22 +27,31 @@ correction interactively (or refine it via a free-text hint, which
 re-proposes the correction without limit) or - with `--auto` - applies
 all corrections automatically.
 
-By default all twenty code quality aspects are checked. The `--include`
+By default all twenty-one code quality aspects are checked. The `--include`
 and `--exclude` options narrow this to an *effective aspect set*: with
 `--include` only, exactly the listed aspects are checked; with
 `--exclude` only, all aspects except the listed ones; with both, the
 included ones minus the excluded ones. An unknown aspect id, or a
 combination which cancels out to an empty set, aborts the skill with an
-error. The twenty aspect ids are:
+error. The twenty-one aspect ids are:
 
 ```text
-A01 FORMATTING     A06 REDUNDANCY       A11 TYPING          A16 SECURITY
-A02 COMPREHENSION  A07 PATTERNS         A12 ERROR-HANDLING  A17 ARCHITECTURE
-A03 CLEANLINESS    A08 COMPLICATEDNESS  A13 MEMORY-LEAK     A18 LOGIC
-A04 SPELLING       A09 CONCISENESS      A14 CONCURRENCY     A19 FLOW
-A05 COMPLEXITY     A10 SMELLS           A15 PERFORMANCE     A20 DEAD-CODE
+A01 FORMATTING     A07 PATTERNS         A13 MEMORY-LEAK    A19 FLOW
+A02 COMPREHENSION  A08 COMPLICATEDNESS  A14 CONCURRENCY    A20 DEAD-CODE
+A03 CLEANLINESS    A09 CONCISENESS      A15 PERFORMANCE    A21 DOCUMENTATION
+A04 SPELLING       A10 SMELLS           A16 SECURITY
+A05 COMPLEXITY     A11 TYPING           A17 ARCHITECTURE
+A06 REDUNDANCY     A12 ERROR-HANDLING   A18 LOGIC
 ```
 
+The `A21 DOCUMENTATION` aspect checks the code documentation in *both*
+directions: it flags functions, methods, classes, and modules - *private
+ones included* - which lack a minimal 1-2 line description in the
+idiomatic documentation convention of the target language, *and* it
+flags excessive comments (narrated decision logs, change history,
+line-by-line explanations of the obvious), comments merely restating
+the code, and comments contradicting the code.
+
 ##  OPTIONS
 
 `--auto`|`-a`:
@@ -60,7 +69,7 @@ A05 COMPLEXITY     A10 SMELLS           A15 PERFORMANCE     A20 DEAD-CODE
 `--include`|`-i`=*aspect*[`,`...]:
     Restrict the checked code quality aspects to the given
     comma-separated list of aspect ids (e.g. `A01,A04`). Without this
-    option, all twenty aspects are checked.
+    option, all twenty-one aspects are checked.
 
 `--exclude`|`-e`=*aspect*[`,`...]:
     Remove the given comma-separated list of aspect ids from the checked
@@ -104,6 +113,12 @@ Lint a directory for all aspects except dead code:
 ❯ /ase-code-lint --exclude A20 src/handlers/
 ```
 
+Lint a directory for the documentation aspect only:
+
+```text
+❯ /ase-code-lint -i A21 src/handlers/
+```
+
 ##  SEE ALSO
 
 [`ase-code-analyze`](../ase-code-analyze/help.md), [`ase-code-resolve`](../ase-code-resolve/help.md), [`ase-code-refactor`](../ase-code-refactor/help.md),

package/plugin/skills/ase-task-grill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ase-task-grill
-argument-hint: "[--help|-h] [--next|-n <option>[,...]] [<id>]"
+argument-hint: "[--help|-h] [--rounds|-r <n>] [--next|-n <option>[,...]] [<id>]"
 description: >
     Interview the user relentlessly about the task plan until reaching a
     shared understanding, resolving each branch of the question decision
@@ -22,7 +22,7 @@ Iteratively Grill a Task Plan
 
 <expand name="getopt"
     arg1="ase-task-grill"
-    arg2="--next|-n=(none|DONE|EDIT|IMPLEMENT|PREFLIGHT)... --int-reuse-task">
+    arg2="--rounds|-r=1 --next|-n=(none|DONE|EDIT|IMPLEMENT|PREFLIGHT)... --int-reuse-task">
     $ARGUMENTS
 </expand>
 
@@ -33,6 +33,7 @@ task plan until reaching a shared understanding.
 
 @${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-common-task.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-common-grill.md
 
 Procedure
 ---------
@@ -52,7 +53,15 @@ Set <args>--int-reuse-task</args>.
         Inherit the always existing <ase-session-id/> from the current context.
         Do not output anything.
 
-    2.  React on task id:
+    2.  If <getopt-option-rounds/> is not a positive integer,
+        only output the following <template/> and then immediately
+        *STOP* processing the entire current skill:
+
+        <template>
+        ⧉ **ASE**: ☻ skill: **ase-task-grill**, ▶ ERROR: invalid `--rounds` value: **<getopt-option-rounds/>**
+        </template>
+
+    3.  React on task id:
 
         <expand name="task-react-id" arg1="ase-task-grill"></expand>
 
@@ -71,62 +80,97 @@ Set <args>--int-reuse-task</args>.
 
 3.  **Iterate Over Task Plan Aspects:**
 
-    Interactively interview the user *relentlessly* about every
-    *essential aspect* of the task plan in <task-content/> *until* reaching a
-    shared understanding and no decisions/questions are left open.
-
-    This especially means that you *MUST* clarify as many aspects as
-    necessary to ensure that for at least the most important decisions,
-    during a subsequent implementation, no essential freedom of choice
-    exists any longer.
-
-    For this process, determine the <n/> essential aspects <aspect-N/>
-    (a one- or two-word-long short identifier like `Foo` or `Bar-Baz`)
-    and the corresponding decision/question <question-N/> where a shared
-    understanding is required.
+    1.  Understand what "grilling" is about:
 
-    Honor also the following checks for identifying the problematic
-    aspects:
+        <expand name="grill-understanding" arg1="the task plan in <task-content/>"></expand>
 
-    -   **Fuzzy Language**:
-        When the user uses vague or overloaded terms instead of a precise
-        or canonical term.
+    2.  Perform <getopt-option-rounds/> grilling *rounds*, numbered
+        <m/> (1-<getopt-option-rounds/>). Each round starts *from
+        scratch* from *only* the *current* <task-content/> -- as
+        updated by all previous rounds -- and *forgets* all questions
+        and answers gathered in previous rounds.
 
-    -   **Conflicting Terminology**:
-        When the user uses a term that conflicts with the existing
-        terminology in the code base.
+        For each round:
 
-    -   **Conflicting Code**:
-        When the user states how something works, check whether the
-        current code state really agrees.
+        1.  INITIALIZE ROUND:
 
-    -   **Non-Concrete Scenarios**:
-        When domain relationships are being discussed, stress-test them
-        with specific scenarios. Invent scenarios that probe edge cases
-        and force the user to be precise about the boundaries between
-        concepts.
+            Set <round-id/> to `GRILLING ROUND <m/>/<getopt-option-rounds/>`
+            if <getopt-option-rounds/> is greater than 1, or to
+            `GRILLING` otherwise (a single round needs no round
+            numbering). Then output only the following <template/>:
 
-    Then create a decisions/questions tree for them. Walk down each
-    branch of this decision tree, resolving dependencies between
-    decisions one-by-one. Ask the questions <question-N/> and determine
-    the corresponding answer <answer-N/>, one at a time.
+            <template>
+            ⧉ **ASE**: <round-id/>: *Relentless Interviewing Until Clarity*
+            </template>
 
-    1.  For each question <question-N/> in the iteration cycle <N/>:
+        2.  DETERMINE QUESTIONS:
+
+            Determine the essential aspects <aspect-N/> (a one- or
+            two-word-long short identifier like `Foo` or `Bar-Baz`, also
+            serving as the topic hint) and the corresponding, very brief
+            but precise decision/question <question-N/> where a shared
+            understanding is required. Each question is chosen to
+            resolve the open points related to the above understanding
+            of grilling, by focusing on the mentioned *Focus Areas* and
+            checking the mentioned *Indicators*.
+
+            For <question-N/> 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/>, encode all *literal aspects*
+            -- file and directory paths, identifiers, symbols, types,
+            commands, options, configuration keys, and literal values --
+            with backticks. Do not output anything.
+
+        3.  DETERMINE CONTEXT:
+
+            For each question, determine its focus area
+            <context-N-focus/> from the mentioned *Focus Areas*.
+            <context-N-severity/>, describing how important this
+            question is.
+
+        4.  SORT QUESTIONS:
+
+            Create a decisions/questions tree for the questions,
+            capturing the dependencies between the decisions. Then
+            *sort* the questions *primarily* by descending focus area
+            order -- first all `DOMAIN`, then all `INTERFACE`, then all
+            `ARCHITECTURE`, and then all `IMPLEMENTATION` ones -- and
+            *secondarily*, within each focus area, by the decision tree
+            order, so that each decision is asked *after* the decisions
+            it depends on. 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.
+
+        5.  For each question <question-N/> in the iteration cycle <N/>,
+            *one at a time*:
+
+            1.  Output the following <template/>:
 
-        1.  Output the following <template/>:
+                <template>
+                <ase-tpl-bullet-signal/> ASPECT <N/>/<n/> ▶ **<context-N-focus/>** (<context-N-severity/>) ▷ **<aspect-N/>**
+                </template>
 
-            <template>
-            <ase-tpl-bullet-signal/> ASPECT <N/>/<n/>: **<aspect-N/>**, QUESTION: **<question-N/>**
-            </template>
+            2.  Determine the answer alternatives:
 
-        2.  Determine the answer alternatives:
+                1.  Check the <task-content/> for the answer <answer-N-1/>,
+                    which reflects the current plan.
 
-            1.  Check the <task-content/> for the answer <answer-N-1/>.
+                2.  Check the code base and your world knowledge and
+                    use this information to find *up to three* grounded
+                    alternative answers <answer-N-K/> (K={2,3,4}), so there
+                    are between two and four answer options in total.
 
-            2.  Check the code base and your world knowledge and
-                use this information to find *up to three* grounded
-                alternative answers <answer-N-K/> (K={2,3,4}), so there
-                are between two and four answer options in total.
+                3.  For each <answer-N-K/> (K={1,2,3,4}) determine
+                    a 1-3 word label <answer-N-K-label/>, and an
+                    ultra brief description <answer-N-K-description/>
+                    of at most *10 words*. Prepend `⚑ ` to the
+                    <answer-N-K-description/> which reflects the current
+                    plan. Do not output anything.
 
             3.  In the following, you *MUST* *NOT* use your built-in
                 <user-dialog-tool/> tool! Instead, you *MUST* just show a
@@ -135,30 +179,46 @@ Set <args>--int-reuse-task</args>.
 
                 Let the user select the <answer-N/> out of the answer
                 alternatives <answer-N-K/> by raising a question with the
-                following custom dialog, where per alternative <answer-N-K/>
-                you determine a brief label <answer-N-K-label/> and a
-                description <answer-N-K-description/>, and you mark the
-                <answer-N-1/> by prefixing its description with
-                `⚝ **CURRENT PLAN** ⚝ `. Emit only the answer lines for the
-                alternatives <answer-N-K/> you actually determined in the
-                previous step (between two and four lines in total):
+                following custom dialog. Emit only the answer lines for
+                the alternatives <answer-N-K/> you actually determined in
+                the previous step (between two and four lines in total),
+                followed by the fixed `SKIP GRILLING` answer option:
 
                 <expand name="custom-dialog" arg1="--other">
                     <aspect-N/>: <question-N/>
-                    <answer-N-1-label/>: ⚝ **CURRENT PLAN** ⚝ - <answer-N-1-description/>
-                    <answer-N-K-label/>: <answer-N-K-description/>
+                    <answer-N-1-label/>: <answer-N-1-description/>
+                    <answer-N-2-label/>: <answer-N-2-description/>
                     [...]
+                    SKIP GRILLING: skip all remaining grilling and continue with the plan update
                 </expand>
 
-                Set <answer-N/> to the selected <result/>.
+                Check the <result/> and dispatch accordingly:
+
+                -   If <result/> is `CANCEL`, only output the following
+                    <template/> and then immediately *STOP* processing
+                    the entire current skill, leaving the plan *untouched*:
+
+                    <template>
+                    ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ▶ status: **grilling stopped**
+                    </template>
+
+                -   If <result/> is `SKIP GRILLING`, ask no further
+                    questions, continue with item 6 below (updating the
+                    plan with the answers gathered so far), and after
+                    item 6 skip all remaining rounds and continue with
+                    item 3.3 below.
+
+                -   Otherwise, strip any leading `OTHER: ` prefix from
+                    <result/> and set <answer-N/> to the remainder.
 
             4.  Output the following <template/>:
 
                 <template>
-                <ase-tpl-bullet-normal/> ASPECT <N/>/<n/>: **<aspect-N/>**, ANSWER: **<answer-N/>**
+                <ase-tpl-bullet-normal/> ASPECT <N/>/<n/> ▶ **<context-N-focus/>** (<context-N-severity/>) ▷ **<aspect-N/>**, ANSWER: **<answer-N/>**
                 </template>
 
-    2.  Finally, update <task-content/> based on all answers <answer-N/>.
+        6.  Update <task-content/> based on all answers <answer-N/>
+            gathered in this round. Do not output anything.
 
     3.  <if condition="the frontmatter of <task-content/> carries a `Created: <text/>` key">
         Set <timestamp-created><text/></timestamp-created> (set

package/plugin/skills/ase-task-grill/help.md

@@ -7,6 +7,7 @@
 
 `ase-task-grill`
     [`--help`|`-h`]
+    [`--rounds`|`-r` *n*]
     [`--next`|`-n` *option*[,...]]
     [*id*]
 
@@ -16,20 +17,43 @@ The `ase-task-grill` skill *relentlessly interviews* the user about
 every *essential aspect* of an existing *task plan* until a *shared
 understanding* is reached and no decisions or questions are left open.
 
-The skill identifies the essential aspects of the plan, builds a
-decision tree of the open questions, and walks down each branch
-one-by-one. For each aspect it presents up to four *grounded*
-alternative answers (the current plan plus alternatives derived from
-the code base and world knowledge), marks the current-plan choice, and
-lets the user pick via an interactive dialog. It honors checks for
-*fuzzy language*, *conflicting terminology*, *conflicting code*, and
-*non-concrete scenarios*. Once all aspects are resolved, the plan is
-updated and persisted, its `Properties:` frontmatter key gains the value
-`grilled`, and the user is offered a hand-off to editing,
-implementation, or preflight.
+The skill identifies the essential aspects of the plan and raises up to
+10 questions per round which resolve its open points. Each question
+carries a `FOCUS-AREA` -- `DOMAIN` (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-2 word `ASPECT`
+hint. The questions are sorted primarily by descending focus area
+importance (`DOMAIN`, `INTERFACE`, `ARCHITECTURE`, `IMPLEMENTATION`)
+and secondarily by the decision tree of their dependencies, so each
+decision is asked after the decisions it depends on. It honors checks
+for *fuzzy language*, *conflicting terminology*, *conflicting code*,
+*non-concrete scenarios*, *unspecified architecture patterns*, and
+*unspecified dependencies*.
+
+In contrast to the batch grilling of `ase-code-edit --grill`, the
+questions are asked *sequentially*, one at a time: each question is
+announced as an `ASPECT n/N ▶ FOCUS ▷ ASPECT, QUESTION` line and then
+raised via an interactive dialog presenting two to four *grounded*
+answer alternatives labeled `A1`-`A4` (the current plan, marked with
+`⚑`, plus alternatives derived from the code base and world knowledge),
+the fixed `SKIP GRILLING` option (skip the remaining questions and
+rounds, keeping the answers gathered so far), and free-text input.
+Cancelling the dialog stops the skill and leaves the plan untouched.
+Once all aspects are resolved, the plan is updated and persisted, its
+`Properties:` frontmatter key gains the value `grilled`, and the user is
+offered a hand-off to editing, implementation, or preflight.
 
 ##  OPTIONS
 
+`--rounds`|`-r` *n*:
+    The number of grill rounds to apply (default: `1`). Each round
+    starts from scratch from only the current plan, as updated by all
+    previous rounds, and re-derives its questions from it, forgetting
+    all questions and answers of previous rounds. With more than one
+    round, each round is announced as `GRILLING ROUND K/L`.
+
 `--next`|`-n` *option*[,...]:
     Automatically answer the user dialog for the next step (at the end
     of this skill). *option* is a single token or a *comma-separated
@@ -63,6 +87,12 @@ Grill the task plan under id `hello`:
 ❯ /ase-task-grill hello
 ```
 
+Grill the current task plan in two rounds:
+
+```text
+❯ /ase-task-grill --rounds 2
+```
+
 Grill the current task plan and then hand off to editing:
 
 ```text
@@ -73,4 +103,4 @@ Grill the current task plan and then hand off to editing:
 
 [`ase-task-edit`](../ase-task-edit/help.md), [`ase-task-reboot`](../ase-task-reboot/help.md), [`ase-task-preflight`](../ase-task-preflight/help.md),
 [`ase-task-implement`](../ase-task-implement/help.md), [`ase-task-view`](../ase-task-view/help.md), [`ase-task-list`](../ase-task-list/help.md),
-[`ase-task-rename`](../ase-task-rename/help.md), [`ase-task-delete`](../ase-task-delete/help.md).
+[`ase-task-rename`](../ase-task-rename/help.md), [`ase-task-delete`](../ase-task-delete/help.md), [`ase-code-edit`](../ase-code-edit/help.md).