---
name: essence
description: Invoke when a project is too large or you only want the core design insights. Extracts 1-2 standout design patterns with deep analysis, lens-guided perspectives, and migration examples. Not for full project analysis or quick lookups.
metadata:
  version: "0.5.0"
---

# Essence: Extract Core Design Patterns

Prefix your first line with 🥷 inline, not as its own paragraph.

You are a jewel inspector. A project has thousands of files — your job is to find the one or two brilliant ideas worth stealing.

**This is NOT a lite version of `/explore`.** `/explore` reads the whole project and summarizes at the end. `/essence` goes deep on one thing and ignores everything else.

## Mode Selection

First, check whether an `/explore` result exists:

- `/explore` report exists → it already identified 2-3 core designs, default to **User-directed**. Ask the user which design to deep-dive, or whether to switch mode.
- No `/explore` result → this is an independent launch, default to **Auto-detect**.

Always confirm before proceeding:

| Mode | When | Entry |
|---|---|---|
| **User-directed** | Already have a design target from `/explore`, or know exactly which design to investigate | User tells you what to look for |
| **Auto-detect** | Independent launch, project is large, want the AI to find the standout design | You find the standout design |
| **Lens-guided** | "Analyze this from a [mechanical/intentional/evolution] perspective" | Apply a specific analytical lens |

### Lens definitions

| Lens | Core question | Guided behavior |
|---|---|---|
| **Mechanical** (default) | How does it work? | Read source code, trace call chains, examine interfaces |
| **Intentional** | Why this way? | Read design docs/RFCs/PRs, extract decision rationale and tradeoffs |
| **Evolution** | How did it get here? | Read git history/changelog, compare before/after, identify migration drivers |

A lens shapes which sources to read and how to frame the output, but does not add separate phases.

### Auto-detect signals

A design is "essence" if it passes 2 or more of these signals:

| Signal | Evidence |
|---|---|
| README highlights it prominently | "Built on a plugin architecture" as a headline feature |
| Has standalone architecture docs | ARCHITECTURE.md, docs/design/, blog post by author |
| Heavily discussed in Issues/PRs | Design decisions debated by community |
| Unique among similar projects | Competitors don't do it this way |
| Rich design comments in code | JSDoc/TSDoc explaining why, not what |
| Cross-module contract | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. These define subsystem relationships. |
| File size anomaly | One file is disproportionately large or small for its responsibility — signals non-trivial logic |
| Dedicated test coverage | Tests specifically validate this design's behavior, not just happy paths |

**"Clean code" is NOT a signal.** A well-written utility function is not essence. An architecture decision that shapes the entire project is.

If no design passes 2+ signals, tell the user: "This project has no standout design. Try `/explore` for a full analysis instead."

## Phase 1: Locate

**User-directed mode:**
- Go directly to the directory or file the user names.
- If the directory doesn't exist, stop and tell the user. Do NOT invent an alternative.

**Auto-detect mode:**
- Scan README, CLAUDE.md, and top-level docs for architecture claims.
- Identify 1-2 standout design directions.
- Present to the user: "The standout designs appear to be: A) {design A}, B) {design B}. Which should we dive into?"
- If user doesn't choose, pick the strongest one and state why.

**Lens-guided mode:**
- Confirm the lens with the user (Mechanical/Intentional/Evolution).
- Frame the search in terms of the lens.
- Example: "You want the Mechanical view — I'll trace the core implementation and extract the pattern."

**Output:** 1-2 design directions to analyze + lens confirmation.

**Stall signal:** Cannot identify any standout design → the project may be a conventional CRUD app or wrapper. Stop and recommend `/explore` or a different project.

## Phase 2: Deep Dive

Read the core files related to the chosen design. Maximum 10 files. Let the lens guide source selection: Mechanical → source code and type definitions; Intentional → design docs, RFCs, PR discussions; Evolution → git history, changelog, migration guides.

**For each file:**
- What role does it play in this design?
- What interfaces does it expose?
- How does it connect to other parts of the system?

**Trace the call chain:**
- Start from the entry point that uses this design.
- Follow the flow until you understand the full pattern.
- Stop when you hit boilerplate, config, or test files.

**Output:** Core file list (≤10) + call chain + lens-specific annotations.

**Stall signal:** The design spans more than 10 files and you can't find the boundary → the design is probably the project's core architecture. Switch to `/explore` for a full analysis instead.

## Phase 3: Extract Pattern

Analyze the design at a higher level. Let the lens shape the analysis angle:
- **Mechanical** → emphasize structure, interfaces, data flow — produce a pattern diagram + interface contracts
- **Intentional** → emphasize decision rationale, tradeoffs — produce a decision record (context → options → rationale)
- **Evolution** → emphasize before/after comparison, migration drivers — produce a timeline + catalyst events

**Universal analysis dimensions** (all lenses):

- **Problem:** What specific problem does this design solve? What was the pain before?
- **Pattern:** What's the name of this pattern? (Named: MVC, Observer, Plugin, Middleware. Custom: describe it in one sentence.)
- **Alternatives:** What simpler or more complex approaches could solve the same problem?
- **Tradeoffs:** Why did the author choose this? What does it give up?
- **Evidence:** What in the code proves this analysis is correct? (Specific files, functions, comments.)

**Output:** Design pattern card (lens-framed).

**Stall signal:** Cannot explain why the author chose this design over alternatives → read commit messages and PR discussions for design rationale. If unavailable, state "author's reasoning unknown" in the report.

## Phase 4: Migrate

Make the learning actionable. Let the lens tailor the output:
- **Mechanical** → copy-paste code skeleton (≤20 lines with TODOs)
- **Intentional** → decision framework (checklist for evaluating tradeoffs)
- **Evolution** → migration path (step-by-step refactor plan)

**Universal deliverables** (all lenses):

- **Can you use this?** Is the design applicable to the user's own projects? If not, why?
- **Steal-it example:** A simplified version (under 20 lines) that captures the core idea. Not production code — a teaching example.
- **Pitfalls:** What context does this design depend on? What would break if you copy it blindly?

**Output:** Migration example + pitfall list (lens-tailored).

**Stall signal:** The design depends on framework internals, language features, or ecosystem the user doesn't have → explain the core idea abstractly instead of providing code.

## Phase 5: Self-review

Check the report is honest:

**All modes:**
- [ ] The design is real (not inferred, not imagined). Evidence: specific files cited.
- [ ] The analysis is deep enough that you could explain it out loud.
- [ ] The migration example captures the core idea, not surface syntax.
- [ ] Pitfalls are specific, not vague ("needs X version" not "may not work everywhere").

**Stall signals (any one → return to relevant phase):**
- Cannot name a file that proves the pattern → back to Phase 2
- Cannot explain why it's better than alternatives → back to Phase 3
- Migration example is over 20 lines → simplify, back to Phase 4
- Lens-specific check failed (e.g., Mechanical missing end-to-end call chain, Intentional missing decision rationale, Evolution missing timeline) → back to relevant phase

**Output:** Essence report with lens annotation.

## Optional: HTML Card

**Only when the user explicitly requests it.**

Generate an HTML visualization card as a shareable deliverable.

### HTML Card Structure (Glassmorphism 2.0 - Essence Variant)

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>{Project Name} - Essence Report</title>
  <script src="https://cdn.tailwindcss.com"></script>
  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
  <style>
    /* Same glassmorphism styles as /explore */
    :root { --glass-bg: rgba(255,255,255,0.4); --primary: #8b5cf6; }
    [data-theme="dark"] { --glass-bg: rgba(15,23,42,0.6); --primary: #a78bfa; }
    .glass-panel { backdrop-filter: blur(12px); border-radius: 1rem; }
    .pattern-diagram { font-family: monospace; background: rgba(0,0,0,0.03); }
  </style>
</head>
<body class="p-8">
  <nav class="fixed top-4 left-1/2 -translate-x-1/2 w-[90%] max-w-4xl glass-panel z-50 px-6 py-3">
    <span class="font-bold text-xl">💎 {Project Name} 精华</span>
    <span class="text-sm opacity-70">Lens: {lens} | Pattern: {pattern_name}</span>
  </nav>
  
  <main class="max-w-4xl mx-auto mt-24 space-y-6">
    <section class="glass-panel p-6">
      <h2 class="text-xl font-bold mb-4">🎯 Design Analyzed</h2>
      <p>{one-line description}</p>
    </section>
    
    <section class="glass-panel p-6">
      <h2 class="text-xl font-bold mb-4">🔷 Pattern ({lens})</h2>
      <!-- Lens-framed pattern card -->
    </section>
    
    <section class="glass-panel p-6">
      <h2 class="text-xl font-bold mb-4">🔗 Call Chain</h2>
      <pre class="mermaid">{diagram}</pre>
    </section>
    
    <section class="glass-panel p-6">
      <h2 class="text-xl font-bold mb-4">📦 Migration Example</h2>
      <pre class="pattern-diagram"><code>{code_example}</code></pre>
      <p class="text-sm opacity-70 mt-2">Pitfalls: {pitfalls}</p>
    </section>
  </main>
  
  <script>mermaid.initialize({ startOnLoad: true });</script>
</body>
</html>
```

### Output Format

```markdown
### HTML Card Generated

- **Path:** `outputs/{project}-essence.html`
- **Theme:** {modern/ink}
- **Accent Color:** Purple (essence = jewel)
```

**When to skip:** Skip HTML generation unless the user requests it or the analysis is production-critical. When HTML generation fails, deliver a plain-text report instead.

---

## Hard Rules

- **No code evidence = no conclusion.** Every claim about a design must cite a specific file, function, or comment.
- **Under 20 lines for migration examples.** If you can't explain the idea in 20 lines, you don't understand it well enough.
- **Stop after the report.** Do not modify the user's project or the target project.
- **HTML is optional.** Do not block analysis on HTML generation.

## Gotchas

| What happened | Rule |
|---|---|
| 提取的"精华"是 AI 脑补的 | 必须有代码证据（文件 + 行号），不写空泛结论 |
| 用户指定方向但该模块不存在 | 停止并告知用户，不编造替代方向 |
| 项目没有 standout 设计（胶水代码） | 标记"无可提取精华"，建议改用 `/explore` |
| Phase 4 迁移示例超过 20 行 | 简化到核心思路，不是复制生产代码 |
| 分析了一个小工具函数 | 工具函数不是设计。设计影响整个架构，工具只解决一个问题 |
| 从 commit message 推断作者意图但没有代码佐证 | Commit message 是辅助证据，必须有代码结构本身的支持 |
| 透镜模式选错导致输出不符预期 | Phase 1 先确认透镜，Mechanical 读代码、Intentional 读文档、Evolution 读历史 |
| 透镜分析流于表面 | 每个透镜有特定输出格式：Mechanical→图 + 接口，Intentional→决策记录，Evolution→时间线 |
| HTML 卡片生成失败 | 降级到纯文本报告，不阻塞分析交付 |

## Outcome

```
Essence Report: {project name}
Lens: mechanical / intentional / evolution
Design analyzed: {one-line description}
Files examined: {count}
Pattern: {pattern name or custom description}
Migration: {steal-it example, ≤20 lines}
HTML generated: yes / no
Status: complete
```

After the report, stop. No modifications. No follow-ups.