SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdevdocs-insights

devdocs-insights

Coding & development

View repository

Updated 10-15 08:12

About this skill

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.

Language Rules

  • Support questions in Chinese and English
  • Unified replies in Chinese
  • Generate documentation 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 learning from
  • The user has found external references (competitors, best practices) worth learning from
  • 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 source
  • Distinguish priorities to avoid requirement bloat

Workflow

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

Output Files

Requirement Append (Single Source)

Confirmed suggestions will be appended to:docs/devdocs/01-requirements.md（Single source of content）

Insight Change Log

File：docs/devdocs/05-insights.md

Downgraded toChange Log—only records the INS number, source, confirmation time, and conversion target, without duplicating requirement content. Avoid 05-insights.md and 01-requirements.md the risk of dual-write desynchronization between them.

## 洞察变更日志

| 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
🎨 UI/UX Review Screenshots/prototypes/review results Usability, visual consistency, accessibility
📄 Documentation Research Technical documentation/design solutions Architecture patterns, implementation solutions, 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 obtain the input methods, focus, 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 Conversion Rules

Conversion Mapping

Suggestion Type Converted to Description
New Feature Suggestion F-XXX (new feature point) Create a new feature point
Optimization Suggestion F-XXX (optimization marker) Mark as optimization type
Bug Fix Directly trigger /devdocs-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 from 01-requirements.md numbering in
  • Acceptance criteria numbering: continue from the existing AC numbering
  • Suggestion ID: INS-XXX (used only in insight documents)

Constraints

Collection Constraints

  • The source of the suggestion 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 conversion
  • Rejected suggestions must have their reasons recorded
  • The complete list must be displayed before batch confirmation
  • The user can adjust suggestion priorities

Conversion Constraints

  • Converted requirements must be traceable to the original suggestions
  • Verifiable acceptance criteria must be generated
  • Optimization-type requirements must be tagged with the [优化] label
  • After conversion, update the suggestion status to 🔄 Converted

Avoid Requirement Bloat

  • A single collection of suggestions must not exceed 10 items
  • Low-priority suggestions can be marked as "Pending"
  • Encourage users to focus on core improvements
  • Regularly clean up expired pending-confirmation suggestions

Skill Collaboration

Scenario Collaborating Skill Description
UI/UX review source /ui-orchestrator Review results can serve as insight sources
Requirement conversion /devdocs-requirements Called: convert insights into requirements
Design changes /devdocs-system-design Trigger: complex improvements require design adjustments
Test supplementation /devdocs-test-cases Trigger: improvement suggestions require test coverage
Simple improvements /devdocs-dev-tasks No architectural changes, split tasks directly
Complex improvements /devdocs-feature Architectural changes present, follow the full process
Bug-type suggestions /devdocs-bugfix Follow the Bug fix process
Requirement updates /devdocs-sync Synchronize document status

Usage Examples

See examples.md

Sub-Agent Summary Format

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

skill: devdocs-insights
source_type: ui_review | doc_research | external_ref | internal_feedback
insights_collected: 3
insights_confirmed: 2
insights_rejected: 1
new_ids:
  features: [F-015, F-016]
  acceptance: [AC-030~AC-033]
status: completed
output_files:
  - docs/devdocs/01-requirements.md
  - docs/devdocs/05-insights.md

Command Options

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

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

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

# 快速模式：直接输入建议列表
/devdocs-insights --quick

Next Steps

After confirming suggestions and converting them into requirements, choose a path based on the improvement complexity:

Path Selection

确认的改进建议
      │
      ▼
评估是否涉及架构变更
      │
      ├── 无架构变更（简单改进）
      │   ├── UI 微调、配置修改、小功能
      │   └── → /devdocs-dev-tasks 直接拆分任务
      │
      └── 有架构变更（复杂改进）
          ├── 新接口、数据模型变更、新模块
          └── → /devdocs-feature 完整流程
                  └── system-design → test-cases → dev-tasks

Architectural Change Determination

Condition Architectural Change Recommended Path
UI/style adjustments only No /devdocs-dev-tasks
Configuration item modifications only No /devdocs-dev-tasks
Add API endpoints Yes /devdocs-feature
Data model changes Yes /devdocs-feature
Add independent modules Yes /devdocs-feature
Third-party service integration Yes /devdocs-feature

Use AskUserQuestion to confirm

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

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

建议路径：
- INS-001 → /devdocs-dev-tasks（直接拆分任务）
- INS-003 → /devdocs-feature（完整流程）

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