aigroup-workflow 1.0.0

package/skills/max/pm-claude-skills/skills/user-research-synthesis/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: user-research-synthesis
+description: Analyze and synthesize user research findings following PM best practices. Use when the user provides user research data, interview transcripts, survey results, or user feedback that needs to be analyzed, synthesized, or summarized into insights and recommendations.
+---
+
+# User Research Synthesis Skill
+
+This skill helps analyze user research data and transform it into actionable insights following a structured methodology.
+
+## Synthesis Framework
+
+### 1. Data Collection Overview
+- **Research Type**: Interviews, surveys, usability tests, etc.
+- **Participant Profile**: Demographics, segments, sample size
+- **Research Questions**: What we sought to learn
+- **Methodology**: How data was collected
+
+### 2. Key Themes Identification
+
+Organize findings into themes using this structure:
+
+**Theme Name**
+- **Description**: What this theme represents
+- **Prevalence**: How many participants mentioned this (e.g., "8 out of 12 participants")
+- **Supporting Quotes**: 2-3 representative quotes
+- **Implication**: What this means for our product
+
+Aim for 4-8 major themes per research effort.
+
+### 3. Pain Points Analysis
+
+For each identified pain point:
+- **Pain Point**: Clear description
+- **Severity**: High/Medium/Low (based on impact and frequency)
+- **Current Workaround**: How users deal with it today
+- **Evidence**: Specific examples from research
+
+### 4. Feature Requests
+
+Categorize requests:
+- **Must-Have**: Critical needs blocking user success
+- **High Value**: Would significantly improve experience
+- **Nice-to-Have**: Incremental improvements
+
+For each request:
+- **Request**: What users asked for
+- **Frequency**: How often it came up
+- **User Quote**: Representative example
+- **Underlying Need**: Why they want this (dig deeper than surface request)
+
+### 5. User Workflow Insights
+
+Document actual workflows observed:
+- **Current State**: How users accomplish tasks today
+- **Pain Points**: Where they struggle
+- **Ideal State**: What they wish they could do
+- **Opportunities**: Where we can add value
+
+### 6. Segmentation Insights
+
+If research reveals distinct user segments:
+- **Segment Name**: Descriptive label
+- **Characteristics**: What defines this segment
+- **Unique Needs**: How their needs differ
+- **Size/Importance**: Relative weight for prioritization
+
+### 7. Competitive Insights
+
+If users mentioned competitors or alternatives:
+- **Competitor/Alternative**: What they use
+- **Why They Use It**: What it does well
+- **Gaps**: What it doesn't do
+- **Switching Barriers**: Why they don't switch fully
+
+### 8. Recommendations
+
+Prioritized recommendations based on insights:
+
+**High Priority**
+- Recommendation with supporting evidence
+- Expected impact
+
+**Medium Priority**
+- Recommendation with supporting evidence
+- Expected impact
+
+**Low Priority / Future Consideration**
+- Recommendation with supporting evidence
+- Expected impact
+
+### 9. Open Questions
+
+Research gaps identified:
+- What we still need to understand
+- Suggested follow-up research
+- Uncertainties requiring validation
+
+## Analysis Guidelines
+
+**When synthesizing interviews:**
+- Look for patterns across multiple participants
+- Note both what users say AND what they do
+- Pay attention to emotional reactions
+- Identify jobs-to-be-done, not just feature requests
+
+**When analyzing quotes:**
+- Use verbatim quotes in "quotation marks"
+- Attribute quotes: [Participant ID, Role, Context]
+- Select quotes that illustrate patterns, not outliers
+- Include both positive and negative feedback
+
+**When identifying themes:**
+- Use descriptive names, not generic labels
+- Provide evidence for each theme
+- Quantify when possible ("7 out of 10 users...")
+- Connect themes to business objectives
+
+## Quality Standards
+
+✅ **Good Synthesis:**
+- Identifies patterns, not just individual responses
+- Connects insights to product decisions
+- Includes supporting evidence for each claim
+- Separates observations from interpretations
+- Prioritizes findings by impact
+
+❌ **Poor Synthesis:**
+- Lists every individual comment
+- Lacks evidence or examples
+- Makes unsupported leaps
+- Focuses on solutions before understanding problems
+- Ignores contradictory data
+
+## Example Theme
+
+```
+**Theme: Information Overload During Onboarding**
+
+**Description**: Users consistently expressed feeling overwhelmed by the amount of information presented during initial setup, leading to incomplete onboarding and delayed time-to-value.
+
+**Prevalence**: 9 out of 12 participants mentioned this issue unprompted
+
+**Supporting Quotes**:
+- "I just wanted to get started, but it felt like I needed to read a manual first" [P3, Marketing Manager]
+- "By the third screen of instructions, I started clicking 'Next' without reading" [P7, Sales Rep]
+- "I wish there was a 'quick start' option for people like me who just want to try it" [P11, Product Designer]
+
+**Implication**: Our current onboarding flow prioritizes completeness over engagement. We should consider a progressive disclosure approach where users can start using the product quickly and learn advanced features contextually.
+
+**Recommended Action**: 
+- Design a "Quick Start" path that gets users to first value in <3 minutes
+- Move advanced configuration to contextual help within the app
+- Test with 5-10 new users before full rollout
+- Expected impact: +20-30% activation rate improvement
+```
+
+## Template Output Structure
+
+When synthesizing research, use this structure:
+
+```markdown
+# User Research Synthesis: [Research Topic]
+
+## Research Overview
+- **Date**: [Date range]
+- **Methodology**: [Interview/Survey/Testing]
+- **Participants**: [Number] [User types]
+- **Research Questions**: 
+  1. [Question 1]
+  2. [Question 2]
+  3. [Question 3]
+
+## Executive Summary
+[2-3 sentence overview of key findings and implications]
+
+## Key Themes
+
+### Theme 1: [Theme Name]
+[Full theme documentation as shown in example above]
+
+### Theme 2: [Theme Name]
+[Full theme documentation]
+
+[Continue with 4-8 themes]
+
+## Pain Points Summary
+
+| Pain Point | Severity | Frequency | Current Workaround |
+|------------|----------|-----------|-------------------|
+| [Pain 1] | High | 10/12 users | [How they cope] |
+| [Pain 2] | Medium | 7/12 users | [How they cope] |
+
+## Feature Requests
+
+### Must-Have
+1. **[Request]** - Mentioned by [X] participants
+   - Quote: "[Representative quote]"
+   - Underlying need: [Why they want this]
+
+### High Value
+[Similar structure]
+
+### Nice-to-Have
+[Similar structure]
+
+## Recommendations
+
+### High Priority (0-3 months)
+1. **[Recommendation]**
+   - Supporting evidence: [Data from research]
+   - Expected impact: [What will improve]
+   - Effort estimate: [Rough sizing]
+
+### Medium Priority (3-6 months)
+[Similar structure]
+
+### Future Consideration (6+ months)
+[Similar structure]
+
+## Open Questions
+1. [Question requiring more research]
+2. [Uncertainty to validate]
+3. [Follow-up study needed]
+
+## Appendix
+- Interview guide used
+- Full participant demographics
+- Raw notes/transcripts (link)
+```

package/skills/max/workflow/brainstorming/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: brainstorming
+description: 需求收集 — 在任何创造性工作之前必须使用。通过协作对话收集和分析功能需求，明确用户意图和成功标准。
+---
+
+# 需求收集与分析
+
+通过自然的协作对话，收集和分析功能需求，把模糊的想法转化为清晰的需求文档。
+
+```
+此阶段只负责"要做什么"，不负责"怎么做"。
+技术方案设计在 solution-design 阶段完成。
+```
+
+## 状态机
+
+```bash
+# 进入此阶段
+bash scripts/harness/workflow-state.sh init <任务名>
+# 完成后推进到需求验证
+bash scripts/harness/workflow-state.sh advance
+```
+
+## 检查清单
+
+你**必须**按顺序完成以下每一项：
+
+1. **探索项目上下文** — 检查文件、文档、近期提交，了解现状
+2. **逐个提问澄清** — 一次一个问题，理解目的、约束、成功标准
+3. **识别用户场景** — 谁会用？在什么场景下？期望什么结果？
+4. **定义功能边界** — 做什么、不做什么、优先级
+5. **撰写需求文档** — 保存到 `.dev-agents/shared/designs/YYYY-MM-DD-<功能名>-requirements.md`
+6. **用户确认** — 请用户审阅需求文档，确认后推进到 validation
+
+## 需求文档结构
+
+```markdown
+# [功能名] 需求文档
+
+## 背景与目的
+为什么要做这个功能？解决什么问题？
+
+## 用户场景
+- 场景 1：作为 [角色]，我希望 [行为]，以便 [价值]
+- 场景 2：...
+
+## 功能需求
+- [ ] FR-1：[具体功能描述]
+- [ ] FR-2：...
+
+## 约束条件
+- 性能要求：...
+- 兼容性要求：...
+- 安全要求：...
+
+## 非功能需求
+- ...
+
+## 范围排除（不做什么）
+- ...
+
+## 成功标准
+- ...
+```
+
+## 铁律
+
+```
+1. 此阶段不做技术方案设计，不选择技术栈，不讨论架构
+2. 每条消息只问一个问题，优先使用选择题
+3. 必须产出需求文档并获得用户确认才能推进
+4. brainstorming 的唯一出口是 validation（需求验证）
+```
+
+## 流程详解
+
+### 理解想法
+
+- 先检查项目当前状态（文件、文档、近期提交）
+- 如果请求涉及多个独立子系统，立即指出需要先拆解
+- 逐个提问来细化想法，聚焦理解目的、约束、成功标准
+- **每条消息只问一个问题**
+
+### 定义需求
+
+- 将用户的描述转化为结构化的功能需求列表
+- 每条需求必须可验证（有明确的通过/不通过标准）
+- 识别隐含需求和边界条件
+- 明确范围排除（什么不做）
+
+### 在现有代码库中工作
+
+- 在收集需求前先探索现有结构
+- 理解现有功能和约束
+- 需求应考虑与现有系统的兼容性
+
+## Red Flags — 停下来
+
+| 信号 | 行动 |
+|------|------|
+| 开始讨论技术方案 | 停下来，技术方案在 design 阶段 |
+| 用户说"直接做吧" | 先完成最小需求文档 |
+| 需求描述了多个独立系统 | 先帮用户拆解为子项目 |
+| 需求中有"待定""之后再说" | 现在就确定，或标记为明确的开放问题 |
+| 想跳过用户确认 | 不允许，用户确认是必须的门禁 |
+
+## 与团队的协作
+
+- 如果涉及 UI/UX，可派遣艾拉参与需求收集
+- 需求文档是后续所有阶段的核心输入
+- 需求确认后进入 validation（需求验证）

package/skills/max/workflow/documentation/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: documentation
+description: 文档更新 — 在测试验证通过后使用。更新相关文档，确保文档与代码一致，包括 API 文档、README、架构文档等。
+---
+
+# 文档更新
+
+测试验证通过后，更新所有受影响的文档，确保文档与代码保持一致。
+
+```
+代码变更后文档不同步 = 技术债。
+此阶段是消除文档债的专门时间窗口。
+```
+
+## 状态机
+
+```bash
+# 确认当前阶段
+bash scripts/harness/workflow-state.sh gate documentation
+# 完成后推进到分支收尾
+bash scripts/harness/workflow-state.sh advance
+```
+
+## 检查清单
+
+你**必须**按顺序完成以下每一项：
+
+1. **列出变更文件** — 基于 git diff 和实现计划，识别本次变更涉及的所有文件
+2. **识别受影响文档** — 哪些文档需要更新？
+3. **逐项更新** — 按优先级更新文档
+4. **一致性检查** — 确认文档与代码一致
+5. **运行文档传感器** — `bash scripts/harness/lint-docs.sh`
+
+## 文档更新优先级
+
+### 必须更新
+
+| 文档类型 | 触发条件 | 更新内容 |
+|---------|---------|---------|
+| **API 文档** | 接口变更 | 参数、返回值、示例 |
+| **README** | 使用方式变更 | 安装步骤、使用示例 |
+| **ARCHITECTURE.md** | 架构变更 | 组件图、数据流 |
+| **模块 CLAUDE.md** | 模块行为变更 | 模块说明、约束 |
+
+### 按需更新
+
+| 文档类型 | 触发条件 | 更新内容 |
+|---------|---------|---------|
+| **代码注释** | 复杂逻辑变更 | 关键算法、设计决策 |
+| **配置文档** | 配置项变更 | 配置说明、默认值 |
+| **部署文档** | 部署流程变更 | 部署步骤、环境要求 |
+
+## 更新原则
+
+- **只更新受影响的文档** — 不做无关的文档改进
+- **保持文档与代码同步** — 描述应反映实际行为
+- **删除过时内容** — 不保留已删除功能的描述
+- **遵循现有文档风格** — 与现有文档保持一致的格式和语气
+
+## 执行方式
+
+- **简单更新**：Max 直接修改
+- **技术文档**：可派遣 Jarvis 更新代码相关文档
+- **知识库文档**：Max 更新 docs/ 下的文档
+
+## 铁律
+
+```
+1. 接口变更必须更新 API 文档
+2. 架构变更必须更新 ARCHITECTURE.md
+3. 更新完成后必须运行 lint-docs.sh 验证
+4. documentation 的唯一出口是 finishing（分支收尾）
+```
+
+## Red Flags — 停下来
+
+| 信号 | 行动 |
+|------|------|
+| 测试验证未通过就更新文档 | 停下来，先回到 testing 阶段 |
+| 文档描述与代码不一致 | 以代码为准，修正文档 |
+| lint-docs.sh 报错 | 修复后重新验证 |
+| 想跳过文档更新 | 检查是否真的没有受影响文档 |

package/skills/max/workflow/entropy-management/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: entropy-management
+description: 定期维护代码库健康度。扫描架构漂移、过期文档、低质量代码，防止技术债积累。应在完成若干任务后或怀疑代码库退化时触发。
+---
+
+# 熵管理（Garbage Collection）
+
+## 概述
+
+AI Agent 会复制仓库中已有的模式——包括不好的模式。随着时间推移，这不可避免地导致漂移。
+手动清理不可持续。熵管理将清理系统化，定期执行，像垃圾回收一样防止技术债积累。
+
+**核心原则**：技术债是高利贷——持续小额偿还远优于积累后大规模清理。
+
+## 铁律
+
+```
+发现的问题不能只修一次——必须同时编码为约束，防止再次发生。
+每次熵管理运行结束后，必须更新质量评分和技术债追踪。
+```
+
+## 触发条件
+
+- 完成 5 个以上任务后（定期维护）
+- Kyle 审查中反复出现同类问题（模式漂移信号）
+- 用户主动要求代码库健康检查
+- 怀疑文档与代码不一致
+- 新成员加入前（确保仓库状态良好）
+
+## 执行流程
+
+### 第一阶段：自动化传感器扫描
+
+运行 Harness 传感器套件收集机器可检测的问题：
+
+```bash
+bash scripts/harness/run-all.sh
+```
+
+记录所有 `[FAIL]` 和 `[WARN]` 项。
+
+### 第二阶段：推理型扫描
+
+自动化传感器无法覆盖的维度，需要人工/Agent 推理检查：
+
+#### 2.1 文档-代码一致性
+
+| 检查项 | 方法 |
+|--------|------|
+| CLAUDE.md 引用路径是否有效 | 逐条验证文件/目录存在 |
+| docs/ 文档描述是否匹配实际行为 | 抽样对比 |
+| SKILL.md 中的流程是否被实际遵循 | 回顾近期任务记录 |
+| 模板是否与当前实践一致 | 对比模板与近期产出 |
+
+#### 2.2 架构漂移检测
+
+| 检查项 | 方法 |
+|--------|------|
+| 是否有文件放在错误目录 | 检查目录约定是否被遵守 |
+| 是否有重复/冗余文件 | 搜索相似文件名和内容 |
+| 技能包结构是否一致 | 抽样检查 SKILL.md 格式 |
+| 协作产物是否在正确位置 | 检查 .dev-agents/shared/ 结构 |
+
+#### 2.3 质量回归检测
+
+| 检查项 | 方法 |
+|--------|------|
+| 近期审查中的高频问题 | 分析 .dev-agents/shared/reviews/ |
+| 是否有被跳过的工作流阶段 | 检查产物完整性 |
+| 是否有"沉默的传感器"（从不报错） | 评估传感器有效性 |
+
+### 第三阶段：修复与编码
+
+对发现的问题分类处理：
+
+| 问题类型 | 处理方式 |
+|---------|---------|
+| 可快速修复的具体问题 | 立即修复（文档更新、文件移动等） |
+| 需要编码为约束的重复模式 | 触发 [转向循环](../../../../docs/steering-loop.md)，添加传感器或更新规则 |
+| 需要架构讨论的系统性问题 | 记录到技术债，与用户讨论 |
+
+### 第四阶段：更新追踪
+
+**必须完成以下更新**（不可跳过）：
+
+1. 更新 `docs/QUALITY_SCORE.md`
+   - 重新评估各维度评分
+   - 添加历史趋势记录
+   - 标注评分变化原因
+
+2. 更新 `docs/tech-debt-tracker.md`
+   - 新发现的技术债添加到"活跃"列表
+   - 已修复的技术债移至"已偿还"列表
+
+3. 更新 `docs/steering-loop.md`
+   - 如果有新增约束，记录到"改进记录"
+
+## 产出清单
+
+每次熵管理运行后，应产出：
+
+```
+✅ 传感器扫描结果（run-all.sh 输出）
+✅ 推理型扫描发现清单
+✅ 修复的问题列表
+✅ 新增的约束/传感器（如有）
+✅ 更新后的 QUALITY_SCORE.md
+✅ 更新后的 tech-debt-tracker.md
+```
+
+## Red Flags — 停下来
+
+| 信号 | 行动 |
+|------|------|
+| 传感器全部通过但直觉上代码库有问题 | 传感器覆盖不足，添加新检查项 |
+| 修复一个漂移又发现三个 | 可能是架构问题，记录技术债后与用户讨论 |
+| 质量评分持续下降 | 需要专项改进，不是熵管理能解决的 |
+| 跳过第四阶段"下次再更新" | 不允许，追踪更新是必须步骤 |
+
+## 关联技能
+
+- **steering-loop** — 将重复问题编码为约束
+- **verification-before-completion** — 修复后验证
+- **systematic-debugging** — 深入调查发现的问题

package/skills/max/workflow/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: finishing-a-development-branch
+description: 当所有实现任务完成并通过审查后使用。验证测试、选择集成方式、清理工作环境。
+---
+
+# 开发分支收尾
+
+## 概述
+
+实现完成后的标准收尾流程：确保测试通过、选择集成方式、清理工作环境。
+
+**核心原则**：有序收尾，不留烂尾分支。
+
+## 铁律
+
+```
+测试未全部通过，不得进入集成选项。
+用户未确认集成方式，不得执行合并操作。
+```
+
+## 前置条件
+
+在使用本技能之前，必须满足：
+- 所有实现任务已完成
+- Kyle 的两阶段审查（规格 + 质量）已通过
+- 最终整体审查已通过
+
+## 流程
+
+### 第一步：运行全量测试
+
+运行项目的完整测试套件，确认所有测试通过。
+
+```
+运行：[项目测试命令]
+预期：所有测试通过，0 失败
+```
+
+**如果有测试失败**：
+- 不进入集成选项
+- 分析失败原因
+- 修复问题
+- 重新运行全量测试
+- 全部通过后才能继续
+
+### 第二步：展示变更摘要
+
+向用户展示：
+- 本次开发涉及的文件数量和主要变更
+- 测试覆盖情况
+- 关键技术决策摘要
+- 未解决的问题或已知限制（如有）
+
+### 第三步：提供集成选项
+
+向用户展示固定的四个选项：
+
+> **开发分支收尾，请选择集成方式：**
+>
+> 1. **本地合并** — 合并到主分支（适合个人项目或小改动）
+> 2. **推送 PR** — 推送分支并创建 Pull Request（适合团队协作）
+> 3. **保留分支** — 暂不合并，保留分支供后续使用
+> 4. **丢弃分支** — 放弃本次开发（需输入 `discard` 确认）
+
+**等待用户选择。不替用户做决定。**
+
+### 第四步：执行用户选择
+
+**选项 1 — 本地合并：**
+```bash
+git checkout main
+git merge <feature-branch>
+```
+- 合并后确认无冲突
+- 合并后运行测试确认通过
+
+**选项 2 — 推送 PR：**
+```bash
+git push -u origin <feature-branch>
+```
+- 创建 PR 并填写摘要
+- PR 描述包含：变更摘要、测试说明、关联的设计文档
+
+**选项 3 — 保留分支：**
+- 确认分支已推送到远程（如需要）
+- 告知用户分支名称和当前状态
+
+**选项 4 — 丢弃分支：**
+- 要求用户输入 `discard` 确认
+- 未确认则不执行
+- 确认后删除分支和清理 worktree（如使用了 worktree）
+
+### 第五步：清理
+
+- 如果使用了 git worktree，执行 `git worktree remove`
+- 清理临时文件
+- 更新任务状态为已完成
+
+## Red Flags — 停下来
+
+| 信号 | 行动 |
+|------|------|
+| 测试没全通过就要合并 | 停，先修复测试 |
+| 没有审查报告就要收尾 | 停，先完成两阶段审查 |
+| 替用户选了集成方式 | 停，展示选项让用户选 |
+| 丢弃分支没要求确认 | 停，必须输入 `discard` |
+| 合并后没跑测试 | 停，合并后必须验证 |
+
+## 关联技能
+
+- **subagent-driven-development** — 本技能的前序（所有任务完成后调用）
+- **verification-before-completion** — 收尾过程中的每次验证