260 lines
12 KiB
Markdown
260 lines
12 KiB
Markdown
---
|
|
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.
|