SuperBizAgent-java/.claude/skills/essence/SKILL.md

name, description, metadata

name	description	metadata
essence	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.	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)

<!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

### 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.