Ase Code Explain

---
name: ase-code-explain
argument-hint: "[--help|-h] <source-reference>"
description: >
    Explains code with WHAT, WHY, ANALOGY, DIAGRAM, CRUXES, and GOTCHAS.
    Use when you want to know how code works or when the user asks "how does this work?"
user-invocable: true
disable-model-invocation: false
effort: high
allowed-tools:
    - "Agent"
---

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md
@${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
@${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

<purpose name="ase-code-explain">
Explain Source Code
</purpose>

<expand name="getopt" arg1="ase-code-explain">
    $ARGUMENTS
</expand>

<objective>
*Analyze* the source code of <getopt-arguments/>, and its directly related source
code, and *explain* it in a *brief*, *standardized*, and *concise* way.
</objective>

<flow>

1.  <step id="STEP 1: Investigate Code Base">
    Investigate the code. If the code base is large, you *MUST* use
    the `Agent` tool (not inline work) to create multiple sub-agents to
    split the investigation task into appropriate chunks.
    </step>

2.  <step id="STEP 2: WHAT and WHY">
    **Explain the WHAT and WHY**.

    First, explain *WHAT* the code does (*functionality*).
    Second, explain *WHY* the code does it (*rationale*).

    Keep your explanations *brief* and *concise*.

    <if condition="<ase-project-boxing/> is equal `black`">

    The project source artifacts are classified as a *black box*, so the
    user wants only the *minimal* surface explanation. Output *only* the
    *WHAT* block (omit the *WHY* block) with the following <template/>:

    <template>
    <ase-tpl-bullet-normal/> **WHAT** (You should know what):
    - [...]
    - [...]
    - [...]
    </template>

    </if>
    <else>

    Output the result with the following <template/>:

    <template>
    <ase-tpl-bullet-normal/> **WHAT** (You should know what):
    - [...]
    - [...]
    - [...]

    <ase-tpl-bullet-normal/> **WHY** (You should know why):
    - [...]
    - [...]
    - [...]
    </template>

    </else>
    </step>

3.  <step id="STEP 3: ANALOGY and DIAGRAM">

    <if condition="<ase-project-boxing/> is equal `black`">

    The project source artifacts are classified as a *black box*, so
    deeper elaboration is *not* wanted. *Skip* this STEP 3 and the
    following STEP 4 entirely: do *not* output any ANALOGY, DIAGRAM,
    CRUXES, or GOTCHAS, and do *not* dispatch any diagram rendering.

    </if>

    **Give insights with ANALOGY and DIAGRAM**.

    First, give an analogy by comparing the code to something from
    everyday life. How can I understand this by something I already
    know? Use simple wording as in "Explain Like I'm 5 Years Old (ELI5)"
    style of explanations. For very complex concepts, use multiple
    analogies.

    Second, draw a diagram to show the control or data flow, code or
    data structure, or code or data relationships. What gives the best
    overall overview of the code?
    Build a Mermaid specification <mermaid-spec/>, choosing the Mermaid
    diagram type per intent: `classDiagram` for class/method structure,
    `sequenceDiagram` for actor/message flow, or `flowchart TB` for
    boxes-and-lines component layouts. Then dispatch the rendering to
    the `ase-meta-diagram` sub-agent by calling the tool
    `Agent(description: "Diagram Rendering", subagent_type:
    "ase:ase-meta-diagram", prompt: <mermaid-spec/>,
    run_in_background: false)` and reproduce its returned fenced code
    block verbatim in the response text. Do *not* hand-draw.

    Keep your explanation *brief* and *concise*.
    Output the result with the following <template/>:

    <template>
    <ase-tpl-bullet-secondary/> **ANALOGY** (You should imagine):
    - [...]
    - [...]
    - [...]

    <ase-tpl-bullet-secondary/> **DIAGRAM** (You should grasp):
    [...]
    </template>
    </step>

4.  <step id="STEP 4: CRUXES and GOTCHAS">
    **Highlight CRUXES and GOTCHAS**.

    First, tell what the *cruxes* of the code are.
    Is there something one should really *notice*?

    Second, tell what the gotchas of the code are.
    Is there something one could really *stumble over*?

    Keep your explanation *brief* and *concise*.
    Output the result with the following <template/>:

    <template>
    <ase-tpl-bullet-signal/> **CRUXES** (You should notice):
    - [...]
    - [...]
    - [...]

    <ase-tpl-bullet-signal/> **GOTCHAS** (You should not stumble over):
    - [...]
    - [...]
    - [...]
    </template>
    </step>

</flow>