--- name: insights description: 将外部参考、调研或评审发现转为 keel 项目的改进事项。普通资料研究不使用此流程。 allowed-tools: Read, Write, Glob, Grep, AskUserQuestion, WebFetch metadata: patterns: [inversion, generator] interaction: multi-turn handoff: yaml-summary-v1 --- # 洞察收集 收集来自 UI/UX 审查、文档调研、外部参考等来源的改进建议，经用户确认后转化为开发需求。 ## 快速开始 **一句话**: 收集优化建议（UI/UX审查、调研、外部参考），确认后转化为开发需求。 **最常见用法**: `/insights`（描述改进来源和建议） **不适合?** 直接加功能→`/feature`，修 Bug→`/bugfix` ## 语言规则 - 支持中英文提问 - 统一中文回复 - 使用中文生成文档 ## 触发条件 - 用户完成 UI/UX 审查，有优化建议 - 用户调研了文档/方案，发现可借鉴点 - 用户发现外部参考（竞品、最佳实践）可借鉴 - 用户有改进想法需要转化为需求 ## 核心理念 ### 洞察来源 ``` ┌─────────────────────────────────────────────────────────────┐ │ 洞察来源 │ ├─────────────────────────────────────────────────────────────┤ │ 🎨 UI/UX 审查 │ 界面问题、交互优化、视觉改进 │ ├─────────────────────────────────────────────────────────────┤ │ 📄 文档调研 │ 技术方案、设计模式、架构参考 │ ├─────────────────────────────────────────────────────────────┤ │ 🔍 外部参考 │ 竞品分析、行业最佳实践、开源项目 │ ├─────────────────────────────────────────────────────────────┤ │ 💡 内部反馈 │ 用户反馈、团队建议、性能监控 │ └─────────────────────────────────────────────────────────────┘ ``` ### 转化流程 ``` 洞察来源 确认阶段 输出阶段 │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ 收集 │ → │ 用户 │ → │ 追加到 │ │ 建议 │ │ 确认 │ │ 需求文档 │ └─────────┘ └─────────┘ └─────────────┘ │ ▼ 部分确认 / 全部确认 / 拒绝 ``` **核心原则**： - 建议必须经过用户确认才能转化为需求 - 保留建议来源的追溯性 - 区分优先级，避免需求膨胀 ## 工作流程 ``` 1. 识别洞察来源 │ ▼ 2. 收集/整理建议 ├── UI/UX 审查结果 ├── 文档调研发现 ├── 外部参考借鉴 └── 内部反馈汇总 │ ▼ 3. 结构化建议列表 ├── 分类整理 ├── 评估影响范围 └── 建议优先级 │ ▼ 4. 用户确认（AskUserQuestion） ├── 逐条确认 ├── 批量确认 └── 调整优先级 │ ▼ 5. 转化为需求 ├── 生成功能点 (F-XXX) ├── 生成验收标准 (AC-XXX) └── 追加到 01-requirements.md │ ▼ 6. 建议后续流程 └── 运行 /system-design 或 /dev-tasks ``` ## 输出文件 ### 需求追加（唯一源） 确认的建议按**类别分流**到四个去处。⛔ 不得一律塞进 `01-requirements.md`——决策类和经验类塞进需求文档，是让「一次性观察」和「长期决策」享受同等待遇、同样不丢。 | 这条洞察是什么 | 去哪 | 现状 | |---|---|---| | **决策**（为什么这么定、权衡了什么）| `02-system-design.md` 的「设计变更记录（ADR 格式）」节，`ADR-XXX` | 已现役 | | **经验**（下次遇到同类问题该怎么办）| `docs/devdocs/patterns/`，由 `/compound` 沉淀 | 已现役 | | **需求**（要做一件新的事）| `01-requirements.md` | 已现役 | | **一次性观察**（这次特有、不会再遇到）| **丢弃** | 新增 | 分流用 AskUserQuestion 问一次，⛔ 不自行判定——「这条是决策还是经验」是语义判断，agent 判不了。 ⚠️ 四类里只有「需求」进 `01-requirements.md`；该文件对**需求类**洞察仍是唯一内容源。 ### 洞察变更日志 **文件**：`docs/devdocs/05-insights.md` 降级为**变更日志**——仅记录 INS 编号、来源、确认时间和转化目标，不重复需求内容。避免 `05-insights.md` 与 `01-requirements.md` 之间的双写不同步风险。 **文件头必填 frontmatter**（realign 扫描依据）： ```yaml --- generated_by: insights spec_version: ins.v1 generated_at: 2026-04-23T10:30:00+08:00 --- ``` ```markdown ## 洞察变更日志 | INS 编号 | 来源 | 确认时间 | 状态 | 转化目标 | |----------|------|----------|------|----------| | INS-001 | 🎨 UI/UX 审查 | 2024-01-15 | 🔄 已转化 | F-015, AC-030~031 | | INS-002 | 📄 文档调研 | 2024-01-15 | ❌ 已拒绝 | -（原因：优先级不足） | ``` ## 建议结构 ### 单条建议格式 ```markdown ### INS-001: <建议标题> | 属性 | 内容 | |------|------| | **来源** | 🎨 UI/UX 审查 / 📄 文档调研 / 🔍 外部参考 / 💡 内部反馈 | | **参考** | <来源链接或描述> | | **现状** | <当前问题或不足> | | **建议** | <改进建议> | | **影响范围** | <涉及模块/功能> | | **优先级** | P0 / P1 / P2 | | **状态** | ⏳ 待确认 / ✅ 已确认 / ❌ 已拒绝 / 🔄 已转化 | **预期收益**： - <收益1> - <收益2> ``` ### 建议列表格式 ```markdown # 洞察收集：<主题> **收集时间**：YYYY-MM-DD **来源类型**：UI/UX 审查 / 文档调研 / 外部参考 ## 建议汇总 | 编号 | 标题 | 来源 | 优先级 | 状态 | |------|------|------|--------|------| | INS-001 | <标题> | 🎨 | P1 | ⏳ | | INS-002 | <标题> | 📄 | P0 | ⏳ | ## 详细建议 ### INS-001: <标题> ... --- ## 确认结果 - [x] INS-001: 已确认 → F-XXX - [ ] INS-002: 待确认 - [x] INS-003: 已拒绝（原因：...） ``` ## 来源类型处理 | 来源 | 输入 | 关注点 | |------|------|--------| | 🎨 UI/UX 审查 | 截图/原型/审查结果 | 可用性、视觉一致性、无障碍性 | | 📄 文档调研 | 技术文档/设计方案 | 架构模式、实现方案、性能优化 | | 🔍 外部参考 | 竞品/开源项目/行业报告 | 竞品优势、行业模式、用户期望 | | 💡 内部反馈 | 用户反馈/团队建议/监控数据 | 用户痛点、团队共识、性能瓶颈 | > **收集建议时，必须读取 [source-types.md](references/source-types.md) 获取各来源类型的输入方式、关注点和示例。** ## 用户确认流程 使用 **AskUserQuestion** 进行交互式确认： ### 单条确认 ``` 建议 INS-001: 按钮对比度不足，影响可读性 来源：🎨 UI/UX 审查 优先级：P1 影响范围：全局按钮组件 是否确认转化为需求？ - 确认（转化为 F-XXX） - 调整优先级后确认 - 拒绝（请说明原因） - 稍后决定 ``` ### 批量确认 ``` 以下建议待确认： | 编号 | 标题 | 优先级 | |------|------|--------| | INS-001 | 按钮对比度不足 | P1 | | INS-002 | 缺少加载状态 | P1 | | INS-003 | 移动端导航问题 | P2 | 请选择： - 全部确认 - 选择性确认（输入编号，如：1,2） - 全部拒绝 - 逐条审查 ``` ## 需求转化规则 ### 转化映射 | 建议类型 | 转化为 | 说明 | |----------|--------|------| | 新功能建议 | F-XXX (新功能点) | 创建新的功能点 | | 优化建议 | F-XXX (优化标记) | 标记为优化类型 | | Bug 修复 | 直接触发 /bugfix | 走 Bug 修复流程 | | 技术改进 | F-XXX (技术债务) | 标记为技术改进 | ### 功能点格式 ```markdown ### F-XXX: <功能名称> [优化] **来源**：INS-XXX (<来源类型>) **优先级**：P0 / P1 / P2 **描述**： <从建议转化的功能描述> **验收标准**： - AC-XXX: <可验证的标准1> - AC-XXX: <可验证的标准2> ``` ### 编号规则 > - 功能点编号：延续 `01-requirements.md` 中的编号（v1: F-XXX / v2: FEAT-XXX） - 验收标准编号：延续现有 AC 编号 - 建议编号：`INS-XXX` ## 约束 ### 收集约束 - [ ] **必须标明建议来源** - [ ] **必须评估影响范围** - [ ] 每条建议必须有明确的现状和改进点 - [ ] 外部参考必须提供来源链接 ### 确认约束 - [ ] **所有建议必须经过用户确认才能转化** - [ ] **拒绝的建议必须记录原因** - [ ] 批量确认前必须展示完整列表 ### 转化约束 - [ ] **转化后的需求必须可追溯到原始建议** - [ ] **必须生成可验证的验收标准** - [ ] 优化类需求必须标记 [优化] 标签 - [ ] 转化后更新建议状态为 🔄 已转化 ## Skill 协作 | 场景 | 协作 Skill | 说明 | |------|-----------|------| | UI/UX 审查来源 | `/ui-orchestrator` | 审查结果可作为洞察来源 | | 需求转化 | `/requirements` | 被调用：洞察转化为需求 | | 设计变更 | `/system-design` | 触发：复杂改进需要设计调整 | | 测试补充 | `/test-cases` | 触发：改进建议需要测试覆盖 | | 简单改进 | `/dev-tasks` | 无架构变更，直接拆分任务 | | 复杂改进 | `/system-design` | 有架构变更，insights 已追加 requirements，直接进入设计 | | Bug 类建议 | `/bugfix` | 走 Bug 修复流程 | | 需求更新 | `/sync` | 同步文档状态 | ## 使用示例 > 详见 [examples.md](references/examples.md) ## 子 Agent 摘要格式 当本 Skill 作为子 Agent 运行时，返回以下结构化摘要： ```yaml skill: insights status: success | failed | partial summary: headline: "收集 3 条洞察，2 条已转化为需求" details: source_type: ui_review | doc_research | external_ref | internal_feedback insights_collected: 3 insights_confirmed: 2 insights_rejected: 1 blockers: [] output_files: - docs/devdocs/01-requirements.md - docs/devdocs/05-insights.md new_ids: features: [F-015, F-016] acceptance: [AC-030~AC-033] insights: [INS-001~INS-003] next_recommended: # 动态：有架构变更 → system-design；简单改进 → dev-tasks skill: system-design # 示例值，实际按架构变更判断 ``` ## 命令选项 ```bash # 标准模式：交互式收集和确认 /insights # 从 URL 提取建议 /insights --url # 从文件提取（如审查报告） /insights --file # 规范升级回扫：INS 条目按新 spec_version 查漏补缺（不新增 INS，仅补字段/格式） /insights --realign ``` > **Realign 模式**（B 类 skill 最小实现）：`--realign` 对 `docs/devdocs/05-insights.md` 按当前 `ins.v1` 扫描结构差距，补齐模板缺字段。详细规则复用 [共享契约](../pipeline/references/realign.md)；推荐用户入口 `/pipeline realign`（编排层会串行调度到本 skill）。 ## 下一步 确认建议并转化为需求后，根据改进复杂度选择路径： ### 路径选择 ``` 确认的改进建议 │ ▼ 评估是否涉及架构变更 │ ├── 无架构变更（简单改进） │ ├── UI 微调、配置修改、小功能 │ └── → /dev-tasks 直接拆分任务 │ └── 有架构变更（复杂改进） ├── 新接口、数据模型变更、新模块 └── → /system-design（insights 已追加 requirements，直接进入设计） └── test-cases → dev-tasks → dev-workflow ``` ### 架构变更判断 | 条件 | 是否架构变更 | 推荐路径 | |------|-------------|----------| | 仅 UI/样式调整 | 否 | `/dev-tasks` | | 仅配置项修改 | 否 | `/dev-tasks` | | 新增 API 接口 | **是** | `/system-design` | | 数据模型变更 | **是** | `/system-design` | | 新增独立模块 | **是** | `/system-design` | | 第三方服务集成 | **是** | `/system-design` | ### 使用 AskUserQuestion 确认 ``` 已确认 X 条改进建议，转化为需求。 检测到以下情况： - INS-001: UI 按钮样式调整 → 无架构变更 - INS-003: 新增导出 API → 涉及架构变更 建议路径： - INS-001 → /dev-tasks（直接拆分任务） - INS-003 → /system-design（有架构变更，进入设计） 是否按建议执行？[是/调整] ```