Skip to content

rse/ase / plugin/skills/ase-code-explain

ase-code-explain

Verified

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?"

FileKindSize
SKILL.mdskill md4.3 KB
help.mdmarkdown1.3 KB
---
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 render <mermaid-spec/>
    at the position of the diagram in the response according to the
    *Diagrams* rule of the skill conventions. 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>

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall