/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 are the *cruxes* of the code. Is there something one should really *notice*?

Second, tell what are the gotchas of the code. 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>