@rse/ase 0.9.4 → 0.9.6

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

@@ -1,6 +1,6 @@
 ---
 name: ase-meta-why
-argument-hint: "[--help|-h] [--depth|-d <N>] <fact>"
+argument-hint: "[--help|-h] [--depth|-d <N>] [--width|-w <M>] <fact>"
 description: >
     Five-Whys Root-Cause Analysis.
 user-invocable: true
@@ -18,7 +18,7 @@ Five-Whys Root-Cause Analysis
 
 <expand name="getopt"
     arg1="ase-meta-why"
-    arg2="--depth|-d=5">
+    arg2="--depth|-d=5 --width|-w=1">
     $ARGUMENTS
 </expand>
 
@@ -34,48 +34,140 @@ addressing surface-level symptoms.
 </objective>
 
 <flow>
-1.  <step id="STEP 1: Determine Problem">
+
+1.  <step id="STEP 1: Restate Problem">
+
     State the problem statement.
 
     <template>
     <ase-tpl-bullet-signal/> **PROBLEM**: <problem/>
     </template>
+
     </step>
 
 2.  <step id="STEP 2: Root-Cause Analysis">
+
     Find the root-cause of <problem/> by following the following iteration cycle.
     Start with a <question/> set equal to the <problem/>.
 
-    Determine the *maximum chain length* from <getopt-option-depth/>: if
-    <getopt-option-depth/> is *non-numeric* or *less than or equal to 0*,
-    use the default *5* instead.
-
-    Start with <n>1</n> (set iteration counter to one).
-    <while condition="<n/> is less than or equal to <getopt-option-depth/>">
-        Ask <question/> and document the answer in <answer/> with the following template:
-        Don't stop at symptoms, keep digging for systemic issues.
-        Multiple root-causes may exist -- explore different branches.
-        Consider technical, domain-specific, process-related, or organizational causes.
-
-        <template>
-        <ase-tpl-bullet-secondary/> **WHY <n/>**: <answer/>
-        </template>
-
-        Then, for the next iteration set <question/> now to be the last <answer/>.
-        The magic is NOT in exactly <getopt-option-depth/> "Why" -- you can <break/>
-        the iteration when you already reached the root-cause.
-        Finally, set <n/> to <n/> + 1 (increment iteration counter).
-    </while>
+    Determine the *maximum chain length* from <getopt-option-depth/>:
+    set <depth/> to <getopt-option-depth/>; if <getopt-option-depth/>
+    is *non-numeric* or *less than or equal to 0*, use the default *5* instead.
+
+    Determine the *maximum chain width* from <getopt-option-width/>:
+    set <width/> to <getopt-option-width/>; if <getopt-option-width/>
+    is *non-numeric* or *less than or equal to 0*, use the default *1* instead.
+
+    -   <if condition="<width/> is less than or equal to 1">
+
+        Walk a *single* causality chain (the classic Five-Whys):
+
+        Start with <n>1</n> (set iteration counter to one).
+
+        <while condition="<n/> is less than or equal to <depth/>">
+
+            Ask <question/> and document the answer in <answer/> with the following template:
+            Don't stop at symptoms, keep digging for systemic issues.
+            Consider technical, domain-specific, process-related, or organizational causes.
+
+            <template>
+            <ase-tpl-bullet-secondary/> **WHY <n/>**: <answer/>
+            </template>
+
+            Then, for the next iteration set <question/> now to be the last <answer/>.
+            The magic is NOT in exactly <depth/> "Why" -- you can <break/>
+            the iteration when you already reached the root-cause.
+            Finally, set <n/> to <n/> + 1 (increment iteration counter).
+
+        </while>
+
+        </if>
+
+    -   <if condition="<width/> is greater than 1">
+
+        Walk a *widened* causality chain: at each "why" level, surface up to
+        <width/> *candidate* sub-causes, then commit to the single most
+        significant one and descend into it (the chain stays single-rooted --
+        the extra candidates are *not* each drilled to their own root-cause).
+        Their purpose is to guard against *premature commitment* to the wrong
+        sub-cause: by enumerating the plausible alternatives at each level, the
+        chosen descent is a *justified* selection rather than the first
+        plausible answer, and the unchosen candidates remain on record as
+        *fallbacks* to backtrack into (see STEP 3) should the chosen path fail
+        validation.
+
+        Remember the *unchosen* candidates of every level (keep them in
+        <fallbacks/>, tagged by their level <n/>), so STEP 3 can backtrack
+        into them.
+
+        Start with <n>1</n> (set iteration counter to one).
+
+        <while condition="<n/> is less than or equal to <depth/>">
+
+            Ask <question/> and surface up to <width/> *distinct*,
+            *non-overlapping* candidate sub-causes, each documented in <answer-k/>.
+            Don't stop at symptoms, keep digging for systemic issues.
+            Explore *different* candidates -- technical, domain-specific,
+            process-related, or organizational causes -- and avoid restating
+            the same cause in different words.
+
+            Start with <k>1</k> (set candidate counter to one).
+            <while condition="<k/> is less than or equal to <width/>">
+                <template>
+                <ase-tpl-bullet-secondary/> **WHY <n/>.<k/>**: <answer-k/>
+                </template>
+                Set <k/> to <k/> + 1 (increment candidate counter).
+            </while>
+
+            Then choose, among the <answer-k/>, the *most causally-significant*
+            candidate -- the one most likely to lead to the true root-cause --
+            and *justify* the choice in one line (state explicitly *why* it
+            beats the other candidates, e.g. it alone also explains the timing,
+            scope, or magnitude of the level's fact). A bare "most significant"
+            is *not* sufficient; if no candidate clearly dominates, say so.
+
+            <template>
+            <ase-tpl-bullet-secondary/> **WHY <n/> → chosen <n/>.<chosen-k/>**: <justification/>
+            </template>
+
+            Record the remaining candidates as <fallbacks/> for level <n/>.
+            Then, for the next iteration, set <question/> to the chosen candidate.
+            You can <break/> the iteration when the chosen candidate already
+            reached its root-cause.
+            Finally, set <n/> to <n/> + 1 (increment iteration counter).
+
+        </while>
+
+        </if>
+
     </step>
 
 3.  <step id="STEP 3: Report Solution">
-    Validate the root-cause by working backwards the causality chain.
-    Propose a solution that addresses and solves the root-cause.
+
+    Validate the root-cause by working backwards along the chosen causality
+    chain: check, level by level, that each chosen sub-cause genuinely *causes*
+    the fact above it (and that fixing the final root-cause would dissolve the
+    whole chain up to the original <problem/>).
+
+    When <width/> is *greater than 1* and this backward validation *fails* at
+    some level -- i.e. the chosen sub-cause does *not* adequately explain the
+    fact above it -- *backtrack*: discard the chosen sub-cause from that level
+    downward, pick the next-best candidate from that level's <fallbacks/>, set
+    <question/> to it, and re-run the STEP 2 widened descent from there. Repeat
+    until a chain survives backward validation or that level's <fallbacks/> are
+    exhausted (then report the strongest chain found and note that no candidate
+    fully validated). This is the payoff of <width/> *greater than 1*: the
+    enumerated alternatives let the analysis *recover* from a wrong turn instead
+    of committing to a mis-rooted chain.
+
+    Propose a solution that addresses and solves the validated root-cause.
     For the proposed solution, optionally directly propose corresponding source code changes.
 
     <template>
     <ase-tpl-bullet-signal/> **SOLUTION**: <solution/>
     </template>
+
     </step>
+
 </flow>
 

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

@@ -8,6 +8,7 @@
 `ase-meta-why`
     [`--help`|`-h`]
     [`--depth`|`-d` *N*]
+    [`--width`|`-w` *M*]
     *fact*
 
 ##  DESCRIPTION
@@ -17,8 +18,16 @@ analysis* technique to the supplied *fact*. The skill iteratively
 asks "why" - up to *N* times (see `--depth`, default five) - to drill
 down from surface symptoms to the underlying root cause, considering
 technical, domain-specific, process-related, and organizational
-causes. After identifying the root cause it proposes a *SOLUTION* that
-addresses it, optionally including concrete source code changes.
+causes. By default it walks a *single* causality chain, but with
+`--width` *M* (> 1) it walks a *widened* chain: at each level it surfaces
+up to *M* candidate sub-causes, descends into the most significant one
+with an explicit justification for the choice, and keeps the unchosen
+candidates as *fallbacks*. If backward validation later shows the chosen
+path was mis-rooted, it *backtracks* into a fallback and re-descends -
+guarding against the classic Five-Whys failure of committing early to the
+wrong sub-cause. After identifying (and validating) the root cause it
+proposes a *SOLUTION* that addresses it, optionally including concrete
+source code changes.
 
 ##  ARGUMENTS
 
@@ -28,6 +37,18 @@ addresses it, optionally including concrete source code changes.
     early once the root cause is reached. Defaults to *5*. A non-numeric
     or non-positive value falls back to the default.
 
+`--width`|`-w` *M*:
+    The *maximum* number of *candidate sub-causes* to surface per "why"
+    level. With the default *1*, the skill walks a single causality chain
+    (classic Five-Whys); with *M* > 1, each level surfaces up to *M*
+    candidate sub-causes, descends into the single most significant one
+    (justifying the choice), and retains the rest as *fallbacks*. During
+    backward validation a mis-rooted choice is *backtracked* into a fallback
+    and re-descended, so the widening actively improves which root-cause is
+    reached rather than merely listing alternatives. The result is still a
+    single, but better-justified, root-cause. A non-numeric or non-positive
+    value falls back to the default.
+
 *fact*:
     The observed *fact* (symptom, problem, or surprising outcome)
     whose root cause should be investigated. The skill implicitly
@@ -47,6 +68,13 @@ Drill down deeper with a tunable chain length of seven:
 ❯ /ase-meta-why -d 7 the production latency spiked after the last deploy
 ```
 
+Weigh several candidate sub-causes per level (with backtracking) to avoid
+committing early to the wrong root-cause:
+
+```text
+❯ /ase-meta-why -w 3 the release was delayed by two weeks
+```
+
 ##  SEE ALSO
 
 `ase-code-analyze`, `ase-code-resolve`, `ase-arch-analyze`.

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

@@ -30,7 +30,7 @@ Condense a Task Plan
 semantics exactly.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -17,10 +17,6 @@ session context) is used. When the deleted task is the current task
 and not the `default` task, the current task id is automatically
 switched back to `default`.
 
-The task plan is stored in `.ase/tasks/`*id*`/plan.md` files of the
-project and can be alternatively deleted with the
-"`ase task delete` *id*" command from outside the agent tool.
-
 ##  ARGUMENTS
 
 *id*:

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

@@ -34,7 +34,7 @@ continued refinement, finalization, or hand-off to implementation or
 preflight.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------
@@ -271,7 +271,7 @@ Set <content-dirty>true</content-dirty>.
             </template>
         </if>
 
-    4.  <if condition="<content/> does not contain '# ✪ TASK PLAN:' AND <instruction/> is empty">
+    4.  <if condition="<content/> does not contain '# ✪ TASK' AND <instruction/> is empty">
         Set <instruction><content/></instruction> (set instruction to content).
         Set <content></content> (set content to empty).
         Set <content-dirty>true</content-dirty>.
@@ -327,9 +327,9 @@ Set <content-dirty>true</content-dirty>.
         Use the following <template/>:
 
         <template>
-        <ase-tpl-head title="TASK-PLAN"/>
+        <ase-tpl-head title="TASK"/>
         <content/>
-        <ase-tpl-foot title="TASK-PLAN"/>
+        <ase-tpl-foot title="TASK"/>
         </template>
 
     4.  *Determine next step*:

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

@@ -19,10 +19,6 @@ through a *chat-driven loop*. The user steers each round via an
 interactive dialog that offers continued refinement, finalization, or
 hand-off to implementation or preflight.
 
-The task plan is stored in `.ase/tasks/`*id*`/plan.md` files of the
-project and can be alternatively edited with the "`ase task edit` *id*"
-command from outside the agent tool.
-
 ##  OPTIONS
 
 `--plan`|`-p` *option*:

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

@@ -31,7 +31,7 @@ Interview the user relentlessly about every essential aspect of the
 task plan until reaching a shared understanding.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -27,10 +27,6 @@ lets the user pick via an interactive dialog. It honors checks for
 updated and persisted, and the user is offered a hand-off to editing,
 implementation, or preflight.
 
-The task plan is stored in `.ase/tasks/`*id*`/plan.md` files of the
-project and can be alternatively edited with the "`ase task edit` *id*"
-command from outside the agent tool.
-
 ##  OPTIONS
 
 `--next`|`-n` *option*[,...]:

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

@@ -30,7 +30,7 @@ Implement a Task Plan
 with a corresponding, complete *change set*.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -12,12 +12,11 @@
 
 ##  DESCRIPTION
 
-The `ase-task-implement` skill performs the *final implementation*
-of a task plan by modifying the corresponding *artifacts* with a
-complete *change set*. The plan is loaded from
-`.ase/tasks/`*id*`/plan.md`, and any optional `IMPLEMENTATION DRAFT`
-section produced by `ase-task-preflight` is used as a hint - the
-plain plan content always overrules the draft.
+The `ase-task-implement` skill performs the *final implementation* of
+a task plan by modifying the corresponding *artifacts* with a complete
+*change set*. The plan is loaded and any optional `IMPLEMENTATION DRAFT`
+section produced by `ase-task-preflight` is used as a hint - the plain
+plan content always overrules the draft.
 
 If the task plan deliberately *omits* the `※ VERIFICATION` section
 (as produced by `ase-code-craft`, `ase-code-refactor`,

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

@@ -30,7 +30,7 @@ Preflight a Task Plan
 for a corresponding, *complete source code change set*.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -30,7 +30,7 @@ Reboot a Task Plan
 based on the existing *WHAT* and *WHY*.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------