insights

Insight Collection

Collect improvement suggestions from sources such as UI/UX reviews, documentation research, and external references, and convert them into development requirements after user confirmation.

Quick Start

One-liner: Collect optimization suggestions (UI/UX review, research, external references), and convert them into development requirements after confirmation.

Most Common Usage: /insights(describe the improvement source and suggestions)

Not suitable? Directly add a feature →/feature, fix a bug →/bugfix

Language Rules

Support questions in Chinese and English
Reply uniformly in Chinese
Generate documents in Chinese

Trigger Conditions

The user has completed a UI/UX review and has optimization suggestions
The user has researched documentation/solutions and found points worth referencing
The user has found external references (competitors, best practices) worth referencing
The user has improvement ideas that need to be converted into requirements

Core Philosophy

Insight Sources

┌─────────────────────────────────────────────────────────────┐
│                      洞察来源                                │
├─────────────────────────────────────────────────────────────┤
│  🎨 UI/UX 审查     │ 界面问题、交互优化、视觉改进            │
├─────────────────────────────────────────────────────────────┤
│  📄 文档调研       │ 技术方案、设计模式、架构参考            │
├─────────────────────────────────────────────────────────────┤
│  🔍 外部参考       │ 竞品分析、行业最佳实践、开源项目        │
├─────────────────────────────────────────────────────────────┤
│  💡 内部反馈       │ 用户反馈、团队建议、性能监控            │
└─────────────────────────────────────────────────────────────┘

Conversion Process

洞察来源                确认阶段                 输出阶段
    │                      │                        │
    ▼                      ▼                        ▼
┌─────────┐          ┌─────────┐            ┌─────────────┐
│ 收集    │    →     │ 用户    │      →     │ 追加到      │
│ 建议    │          │ 确认    │            │ 需求文档    │
└─────────┘          └─────────┘            └─────────────┘
                          │
                          ▼
                    部分确认 / 全部确认 / 拒绝

Core Principles：

Suggestions must be confirmed by the user before they can be converted into requirements
Preserve traceability of the suggestion sources
Distinguish priorities to avoid requirement bloat

Workflow

1. 识别洞察来源
   │
   ▼
2. 收集/整理建议
   ├── UI/UX 审查结果
   ├── 文档调研发现
   ├── 外部参考借鉴
   └── 内部反馈汇总
   │
   ▼
3. 结构化建议列表
   ├── 分类整理
   ├── 评估影响范围
   └── 建议优先级
   │
   ▼
4. 用户确认（AskUserQuestion）
   ├── 逐条确认
   ├── 批量确认
   └── 调整优先级
   │
   ▼
5. 转化为需求
   ├── 生成功能点 (F-XXX)
   ├── 生成验收标准 (AC-XXX)
   └── 追加到 01-requirements.md
   │
   ▼
6. 建议后续流程
   └── 运行 /system-design 或 /dev-tasks

Output Files

Requirement Addendum (Single Source)

Confirmed suggestions are routed bycategoryto four destinations. ⛔ Do not stuff them all into 01-requirements.md——putting decision-type and experience-type items into the requirements document gives "one-off observations" and "long-term decisions" the same treatment and ensures neither is lost.

What this insight is	Where it goes	Current State
Decision(why it was decided this way, what trade-offs were made)	`02-system-design.md` the "Design Change Record (ADR format)" section of`ADR-XXX`	Already in service
Experience(what to do next time a similar problem is encountered)	`docs/devdocs/patterns/`，by `/compound` accumulated	Already in service
Requirement(a new thing to do)	`01-requirements.md`	Already in service
One-off Observation(specific to this time and will not be encountered again)	Discard	New

For routing, use AskUserQuestion to ask once. ⛔ Do not decide on your own——"is this a decision or an experience" is a semantic judgment that the agent cannot make.

⚠️ Of the four categories, only "Requirement" goes into 01-requirements.md; for that file,requirement-typeinsights are still the only content source.

Insight Change Log

File：docs/devdocs/05-insights.md

Downgraded to achange log——records only the INS number, source, confirmation time, and conversion target, without repeating requirement content. This avoids the risk of write desynchronization between 05-insights.md and 01-requirements.md .

Required frontmatter in the file header(basis for realign scanning):

---
generated_by: insights
spec_version: ins.v1
generated_at: 2026-04-23T10:30:00+08:00
---

## 洞察变更日志

| INS 编号 | 来源 | 确认时间 | 状态 | 转化目标 |
|----------|------|----------|------|----------|
| INS-001 | 🎨 UI/UX 审查 | 2024-01-15 | 🔄 已转化 | F-015, AC-030~031 |
| INS-002 | 📄 文档调研 | 2024-01-15 | ❌ 已拒绝 | -（原因：优先级不足） |

Suggestion Structure

Single Suggestion Format

### INS-001: <建议标题>

| 属性 | 内容 |
|------|------|
| **来源** | 🎨 UI/UX 审查 / 📄 文档调研 / 🔍 外部参考 / 💡 内部反馈 |
| **参考** | <来源链接或描述> |
| **现状** | <当前问题或不足> |
| **建议** | <改进建议> |
| **影响范围** | <涉及模块/功能> |
| **优先级** | P0 / P1 / P2 |
| **状态** | ⏳ 待确认 / ✅ 已确认 / ❌ 已拒绝 / 🔄 已转化 |

**预期收益**：
- <收益1>
- <收益2>

Suggestion List Format

# 洞察收集：<主题>

**收集时间**：YYYY-MM-DD
**来源类型**：UI/UX 审查 / 文档调研 / 外部参考

## 建议汇总

| 编号 | 标题 | 来源 | 优先级 | 状态 |
|------|------|------|--------|------|
| INS-001 | <标题> | 🎨 | P1 | ⏳ |
| INS-002 | <标题> | 📄 | P0 | ⏳ |

## 详细建议

### INS-001: <标题>
...

---

## 确认结果

- [x] INS-001: 已确认 → F-XXX
- [ ] INS-002: 待确认
- [x] INS-003: 已拒绝（原因：...）

Source Type Handling

Source	Input	Focus Areas
🎨 UI/UX Review	Screenshots/Prototypes/Review Results	Usability, visual consistency, accessibility
📄 Documentation Research	Technical Documentation/Design Proposals	Architecture patterns, implementation approaches, performance optimization
🔍 External References	Competitors/Open Source Projects/Industry Reports	Competitor advantages, industry patterns, user expectations
💡 Internal Feedback	User Feedback/Team Suggestions/Monitoring Data	User pain points, team consensus, performance bottlenecks

When collecting suggestions, you must read source-types.md to get the input methods, focus areas, and examples for each source type.

User Confirmation Process

Use AskUserQuestion for interactive confirmation:

Single Confirmation

建议 INS-001: 按钮对比度不足，影响可读性

来源：🎨 UI/UX 审查
优先级：P1
影响范围：全局按钮组件

是否确认转化为需求？
- 确认（转化为 F-XXX）
- 调整优先级后确认
- 拒绝（请说明原因）
- 稍后决定

Batch Confirmation

以下建议待确认：

| 编号 | 标题 | 优先级 |
|------|------|--------|
| INS-001 | 按钮对比度不足 | P1 |
| INS-002 | 缺少加载状态 | P1 |
| INS-003 | 移动端导航问题 | P2 |

请选择：
- 全部确认
- 选择性确认（输入编号，如：1,2）
- 全部拒绝
- 逐条审查

Requirement Transformation Rules

Transformation Mapping

Suggestion Type	Transform Into	Description
New Feature Suggestion	F-XXX (New Feature Point)	Create a new feature point
Optimization Suggestion	F-XXX (Optimization Mark)	Mark as optimization type
Bug Fix	Directly trigger /bugfix	Follow the Bug fix process
Technical Improvement	F-XXX (Technical Debt)	Mark as technical improvement

Feature Point Format

### F-XXX: <功能名称> [优化]

**来源**：INS-XXX (<来源类型>)
**优先级**：P0 / P1 / P2

**描述**：
<从建议转化的功能描述>

**验收标准**：
- AC-XXX: <可验证的标准1>
- AC-XXX: <可验证的标准2>

Numbering Rules

Feature point numbering: Continue the numbering from 01-requirements.md (v1: F-XXX / v2: FEAT-XXX)
Acceptance criteria numbering: Continue the existing AC numbering
Suggestion numbering:INS-XXX

Constraints

Collection Constraints

The suggestion source must be indicated
The scope of impact must be assessed
Each suggestion must have a clear current state and improvement point
External references must provide source links

Confirmation Constraints

All suggestions must be confirmed by the user before transformation
Rejected suggestions must have their reasons recorded
The complete list must be displayed before batch confirmation

Transformation Constraints

Transformed requirements must be traceable to the original suggestion
Verifiable acceptance criteria must be generated
Optimization-type requirements must be marked with the [优化] tag
After transformation, update the suggestion status to 🔄 Transformed

Skill Collaboration

Scenario	Collaborating Skill	Description
UI/UX Review Source	`/ui-orchestrator`	Review results can serve as an insight source
Requirement Transformation	`/requirements`	Invoked: Insights transformed into requirements
Design Changes	`/system-design`	Trigger: Complex improvements require design adjustments
Test Supplementation	`/test-cases`	Trigger: Improvement suggestions require test coverage
Simple Improvements	`/dev-tasks`	No architecture changes, directly split tasks
Complex Improvements	`/system-design`	With architecture changes, insights have appended requirements, directly proceed to design
Bug-type Suggestions	`/bugfix`	Follow the Bug fix process
Requirement update	`/sync`	Sync document status

Usage example

See examples.md

Sub-Agent summary format

When this Skill runs as a sub-Agent, return the following structured summary:

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       # 示例值，实际按架构变更判断

Command options

# 标准模式：交互式收集和确认
/insights

# 从 URL 提取建议
/insights --url <url>

# 从文件提取（如审查报告）
/insights --file <path>

# 规范升级回扫：INS 条目按新 spec_version 查漏补缺（不新增 INS，仅补字段/格式）
/insights --realign

Realign mode(minimal implementation for type B skills):--realign For docs/devdocs/05-insights.md scan for structural gaps according to the current ins.v1 , and fill in the missing fields in the template. Detailed rules reuse shared contract; recommended user entry point /pipeline realign(the orchestration layer will schedule to this skill serially).

Next steps

After confirming the recommendation and converting it into a requirement, choose a path based on the improvement complexity:

Path selection

确认的改进建议
      │
      ▼
评估是否涉及架构变更
      │
      ├── 无架构变更（简单改进）
      │   ├── UI 微调、配置修改、小功能
      │   └── → /dev-tasks 直接拆分任务
      │
      └── 有架构变更（复杂改进）
          ├── 新接口、数据模型变更、新模块
          └── → /system-design（insights 已追加 requirements，直接进入设计）
                  └── test-cases → dev-tasks → dev-workflow

Architecture change determination

Condition	Whether it is an architecture change	Recommended path
UI/style adjustments only	No	`/dev-tasks`
Configuration item modifications only	No	`/dev-tasks`
New API endpoint	Yes	`/system-design`
Data model change	Yes	`/system-design`
New standalone module	Yes	`/system-design`
Third-party service integration	Yes	`/system-design`

Use AskUserQuestion to confirm

已确认 X 条改进建议，转化为需求。

检测到以下情况：
- INS-001: UI 按钮样式调整 → 无架构变更
- INS-003: 新增导出 API → 涉及架构变更

建议路径：
- INS-001 → /dev-tasks（直接拆分任务）
- INS-003 → /system-design（有架构变更，进入设计）

是否按建议执行？[是/调整]