Reorganize workspace and archive skill artifacts

skill-workbench/docs/explore-essence-follow/latest-design.md

@@ -0,0 +1,270 @@
+# Explore / Essence / Follow 最新设计总结
+
+**版本基线**：v0.5.0  
+**对应 skill 本体**：`skill-workbench/generated-skills/skills/`  
+**历史来源**：
+
+- `skill-workbench/history/changelog/2026-04-30-skills-v0.5.0-consolidation.md`
+- `skill-workbench/history/docs/superpowers/specs/`
+- `skill-workbench/history/docs/superpowers/changelog/`
+
+## 一句话定位
+
+`explore`、`essence`、`follow` 是一组学习型 skill family：
+
+- `explore` 负责项目级理解。
+- `essence` 负责深挖 1-2 个最值得迁移的核心设计。
+- `follow` 负责基于已有报告做交互式跟学。
+
+三者不是“深浅不同的同一个技能”，而是学习链路中的三个不同角色。
+
+## 设计背景
+
+早期 superpowers 设计试图覆盖完整学习过程，但在实践中出现了几个问题：
+
+1. 阶段过多，`explore` 同时承担项目理解、深度分析、教学输出，边界不清。
+2. `/essence` 曾被误设计成 `/explore` 的轻量版，导致无法稳定聚焦“值得偷走的设计”。
+3. `/follow` 曾倾向重新扫描项目，削弱了它“基于已有报告教学”的定位。
+4. HTML、Deep Fission、Verify 等输出阶段让 skill 变重，增加上下文和执行成本。
+5. 历史 docs 中存在过时 proposal、plan 和已删除技能引用，需要收敛为当前真实实现。
+
+v0.5.0 的核心改造是：**拆清职责，减少阶段，只保留能稳定触发、稳定产出的学习动作。**
+
+## 三技能职责边界
+
+| Skill | 核心问题 | 输入 | 输出 | 不做什么 |
+| --- | --- | --- | --- | --- |
+| `explore` | 这个项目是什么，为什么值得学，从哪里开始？ | 新项目、代码仓库、文档仓库、skill 仓库 | 项目学习报告、结构图、2-3 个核心设计概览 | 不做深度模式提取，不做互动教学 |
+| `essence` | 这个项目最值得偷走的设计是什么？ | 明确设计目标，或需要自动找 standout design | 设计模式卡、证据链、迁移示例 | 不做全项目概览，不做普通代码讲解 |
+| `follow` | 如何基于已有报告一步步学会？ | 已有 `/explore` 或 `/essence` 报告 | Runnable 或 Reader 跟学会话 | 不重新扫描项目，不替用户执行代码 |
+
+## 推荐学习链路
+
+```text
+第一次接触项目
+  ↓
+/explore
+  产出项目定位、结构、主流程、核心设计候选
+  ↓
+/essence
+  选择一个核心设计做深挖，提炼可迁移模式
+  ↓
+/follow
+  基于 explore/essence 报告做交互式学习
+```
+
+也可以单独使用：
+
+- 只想快速建立全局认知：只用 `explore`。
+- 已经知道要研究哪个设计：直接用 `essence` 的 User-directed 模式。
+- 已经有报告，想按教程学：直接用 `follow`。
+
+## Explore 最新设计
+
+### 定位
+
+`explore` 是项目地图绘制器。它回答：
+
+- 这个项目是什么？
+- 为什么值得研究？
+- 顶层结构如何组织？
+- 学习入口在哪里？
+- 有哪 2-3 个核心设计值得后续深挖？
+
+### 当前阶段
+
+v0.5.0 将原来的 5 Phase 收敛为 4 Phase：
+
+1. **Positioning & Structure**
+   - 合并早期 Positioning 和 Structure。
+   - 输出项目定位、学习价值、顶层结构、入口区域。
+2. **Flow**
+   - 仅代码仓库执行。
+   - 追踪主运行流或请求流，聚焦 golden path。
+3. **Start Path**
+   - 仅代码仓库且可运行/可观察时执行。
+   - 给出最小启动路径、第一条命令或第一处观察点。
+4. **Core Designs**
+   - 总结 2-3 个核心设计或核心想法。
+   - 保持概览深度，为 `essence` 提供候选对象。
+
+### 类型分流
+
+`explore` 必须先识别项目类型：
+
+- **Code repository**：执行完整 4 Phase。
+- **Skill / docs / knowledge repository**：跳过 Flow 和 Start Path，改用结构图、概念图或 workflow 图。
+- **Template / scaffold repository**：Flow 和 Start Path 可以保持轻量。
+
+### 关键约束
+
+- 不做 `/essence` 级别深挖。
+- 不做 `/follow` 式互动教学。
+- 不保留 Verify、Deep Fission、HTML Output 等已退休阶段。
+- 最终必须至少包含一个图：代码仓库用架构/流程图，非代码仓库用结构/想法/workflow 图。
+
+## Essence 最新设计
+
+### 定位
+
+`essence` 是“宝石检查器”。它不是 `/explore` 的轻量版，而是专门回答：
+
+> 这个项目里哪 1-2 个设计最值得迁移到我自己的工程里？
+
+### 模式
+
+| Mode | 触发场景 | 行为 |
+| --- | --- | --- |
+| User-directed | 用户已有目标，或来自 `/explore` 的核心设计候选 | 直接深挖用户指定设计 |
+| Auto-detect | 独立启动，用户希望 AI 自动找亮点 | 扫 README、docs、结构和信号，提出 1-2 个候选 |
+| Lens-guided | 用户指定 mechanical / intentional / evolution 视角 | 按透镜选择证据来源和输出框架 |
+
+### 透镜
+
+- **Mechanical**：它如何工作？读代码、接口、调用链。
+- **Intentional**：为什么这样设计？读设计文档、RFC、PR、权衡。
+- **Evolution**：它如何演化到这里？读 changelog、git 历史、迁移记录。
+
+### 当前阶段
+
+1. **Locate**
+   - 找到 1-2 个候选设计方向。
+   - 自动模式要求 standout design 至少满足 2 个信号。
+2. **Deep Dive**
+   - 最多读 10 个核心文件。
+   - 追踪调用链或证据链，避免扩散成全项目分析。
+3. **Extract Pattern**
+   - 提炼问题、模式、替代方案、权衡和证据。
+4. **Migrate**
+   - 给出可迁移方式和最小示例。
+   - 示例必须足够小，避免复制生产代码。
+5. **Self-review**
+   - 检查是否有证据、是否解释了权衡、是否能迁移。
+
+### 关键约束
+
+- “代码干净”不是 essence 信号。
+- 如果没有 standout design，应明确建议改用 `explore`。
+- 如果设计边界超过 10 个文件且无法收敛，应改用 `explore`。
+- HTML Card 只是显式请求时的可选输出，不是默认阶段。
+
+## Follow 最新设计
+
+### 定位
+
+`follow` 是跟学教练。它不做新分析，只基于已有 `/explore` 或 `/essence` 报告，带用户一步步学习。
+
+### 前置条件
+
+必须存在以下之一：
+
+- `/explore` 报告
+- `/essence` 报告
+
+如果没有，必须拒绝并引导用户先运行 `explore` 或 `essence`。
+
+### 模式
+
+| Mode | 来源 | 行为 |
+| --- | --- | --- |
+| Runnable | `/explore` 报告确认是可运行代码仓库 | 从环境、启动、观察和安全修改开始 |
+| Reader | 非代码仓库，或来自 `/essence`，或用户专注设计学习 | 围绕核心设计做分层阅读和推理练习 |
+
+### 当前流程
+
+**Runnable**：
+
+1. 确认环境和依赖。
+2. 让用户运行项目。
+3. 让用户做一个安全小改动。
+4. 一起走主流程。
+5. 给一个小练习。
+6. 回顾学习结果。
+
+**Reader**：
+
+1. 围绕设计或架构想法设定学习目标。
+2. 按“问题 → 方法 → 实现 → 权衡”讲解。
+3. 通过问题检查理解。
+4. 用图或结构总结连接文件和设计。
+5. 给一个迁移/推理练习。
+6. 回顾学习结果。
+
+### 关键约束
+
+- 不重新扫描项目。
+- 不执行命令或替用户写代码。
+- 不新增第三种模式。
+- 不只说“去读这个文件”，必须说明这个文件体现什么设计、为什么重要、看什么。
+
+## v0.5.0 最重要的收敛
+
+### 1. Explore 从 5 Phase 收敛到 4 Phase
+
+早期 Positioning 和 Structure 拆开导致报告啰嗦。v0.5.0 合并为 `Positioning & Structure`，让 `explore` 更像项目地图，而不是流水账。
+
+### 2. Essence 补齐上下文感知
+
+`essence` 会先判断是否已有 `/explore` 结果：
+
+- 有结果：默认 User-directed，让用户从候选设计中选择。
+- 无结果：默认 Auto-detect，自行寻找 standout design。
+
+这避免了 `essence` 在已有上下文时重复扫描。
+
+### 3. Follow 不再重扫
+
+`follow` 的核心价值是“基于报告教学”。如果它重新扫描项目，就会变成另一个 explore。v0.5.0 明确它必须读取前置报告，按报告决定 Runnable 或 Reader。
+
+### 4. Reader 模式从文件级提升到设计级
+
+早期 Reader 容易变成“带你读一个文件”。v0.5.0 改成围绕设计概念学习：问题、方法、实现、权衡。
+
+### 5. 删除过期阶段和死引用
+
+已退休内容包括：
+
+- Deep Fission
+- Verify 阶段
+- 默认 HTML Output
+- 旧 `/map`、`/fission` 等已不存在技能引用
+
+## 当前产物边界
+
+```text
+skill-workbench/
+├── generated-skills/
+│   └── skills/
+│       ├── explore/
+│       ├── essence/
+│       └── follow/
+├── docs/
+│   └── explore-essence-follow/
+│       └── latest-design.md
+└── history/
+    ├── changelog/
+    └── docs/superpowers/
+```
+
+- `generated-skills/skills/` 只放可安装 skill 本体。
+- `docs/explore-essence-follow/latest-design.md` 保存最新设计总结。
+- `history/` 保留旧设计、changelog、handoff 和过时 specs，作为考古来源。
+
+## 何时修改哪一层
+
+| 变更类型 | 修改位置 |
+| --- | --- |
+| skill 行为变更 | `skill-workbench/generated-skills/skills/{skill}/SKILL.md` |
+| 最新设计说明变更 | `skill-workbench/docs/explore-essence-follow/latest-design.md` |
+| 历史记录 | `skill-workbench/history/`，不要覆盖 |
+| 验证材料 | `skill-workbench/validation/` |
+
+## 当前结论
+
+这组三技能已经形成清晰分工：
+
+- `explore` 是入口：建立项目级地图。
+- `essence` 是深挖：提炼可迁移设计。
+- `follow` 是教学：基于报告引导用户学会。
+
+后续改进应避免把三者重新合并。最重要的维护原则是：**保持边界比增加功能更重要。**