blueprint-discovery

蓝图发现

处理蓝图工作流的第 1 至 5 步：完善想法、研究决策信号、访谈决策、收集验收标准以及功能分类。

输入

feature_description: string  # Raw feature description from user

1. 完善想法

在深入发现前快速澄清。通过 1-3 个有针对性的问题，尽早发现误解。

触发条件：

• feature_description 少于 100 个字符
• 包含不确定表述：“maybe”“probably”“something like”“I think”“not sure”
• 缺少核心要素：没有明确的动作动词，或没有明确的主体

跳过条件：

• 描述详细（超过 200 个字符且意图明确）
• 用户说“proceed”或“skip refinement”
• 有复现步骤的 Bug 修复

触发时：

AskUserQuestion:
  question: "Quick check - what's the primary goal?"
  header: "Goal"
  options:
    - label: "Add new capability"
      description: "Feature that doesn't exist yet"
    - label: "Fix broken behavior"
      description: "Something that should work but doesn't"
    - label: "Improve existing feature"
      description: "Enhancement to current functionality"
    - label: "Refactor/cleanup"
      description: "Better code without behavior change"

后续提问（如果回答仍有遗漏）：

If goal == "Add new capability":
  AskUserQuestion:
    question: "Who will use this and when?"
    header: "Context"
    options:
      - label: "End users in the app"
      - label: "Admins/internal team"
      - label: "Developers/API consumers"
      - label: "Automated systems"

If goal == "Fix broken behavior":
  AskUserQuestion:
    question: "How does it fail?"
    header: "Symptom"
    options:
      - label: "Error/crash"
      - label: "Wrong output"
      - label: "Missing data"
      - label: "Performance issue"

最多提问 3 次。 完善后：

refined_description = original + goal + context/symptom (if asked)

提供跳过选项：

“明白了：{refined_description}。准备继续，还是需要进一步澄清？”

2. 研究决策信号

完善想法时，收集信号，以便在 blueprint-research 中做出研究决策。

从对话中推断：

信号	检测方式
user_familiarity	能指出现有代码示例？知道文件所在位置？→ high
user_intent	“Quick fix”“ship today”→ speed；“want it right”“research first”→ thoroughness
topic_risk	关键词：auth、payment、stripe、security、encrypt、API key、webhook → high
uncertainty_level	“Not sure how”“what's the best way”，或正在探索选项 → high

如果信号不明确，可快速询问：

AskUserQuestion:
  question: "What matters more for this task?"
  header: "Priority"
  options:
    - label: "Get it done fast"
      description: "Good enough solution, ship quickly"
    - label: "Get it done right"
      description: "Research best practices first"

保存信号，供研究阶段使用。

3. 访谈决策

建议进行访谈的情况：

• 功能描述少于 2 句话
• 包含不确定词语：“maybe”“probably”“something like”“not sure”
• 涉及多个利益相关方或系统
• 用户似乎不确定

跳过访谈的情况：

• 有明确复现步骤的 Bug 修复
• 小型且定义明确的任务（可能涉及少于 3 个文件）
• 引用了现有规格说明/PRD 的功能

如果建议访谈：

AskUserQuestion:
  question: "This feature could benefit from a requirements interview. Explore in depth first?"
  options:
    - "Yes, interview me first" → Invoke /interview with feature_description
    - "No, proceed to planning" → Continue

4. 验收标准

必须询问“完成”的定义。

验收标准仅描述功能行为。质量门槛（测试、lint、评审）由其他 Agent 处理。

AskUserQuestion:
  question: "What behavior must work for this feature to be done?"
  header: "Done when"
  multiSelect: true
  options:
    - label: "User can perform action"
      description: "Feature enables a specific user action"
    - label: "System responds correctly"
      description: "API/backend behaves as expected"
    - label: "UI displays properly"
      description: "Visual elements render correctly"
    - label: "Data is persisted"
      description: "Changes are saved to database"

良好的验收标准示例：

• “已认证用户可以登录并跳转到仪表盘”
• “表单会在提交前验证电子邮件格式”
• “API 对不存在的资源返回 404”

不佳的验收标准示例（由其他 Agent 处理）：

• “测试通过”→ always-works-verifier
• “代码已评审”→ quality-gate
• “没有 lint 错误”→ slop-remover

记录每项标准的验证方法：

标准	验证方式
用户可以登录	curl -X POST /login 或手动验证
表单会验证	rspec spec/features/signup_spec.rb
API 返回 404	curl /api/nonexistent

5. 功能分类

类型	检测关键词	操作
UI	page、component、form、button、modal、design、view、template	检查设计系统
DevOps	terraform、ansible、infrastructure、cloud、docker、deploy、server	委派给 devops-plan
API	endpoint、route、controller、request、response、REST、GraphQL	标准流程
Data	migration、model、schema、database、query	标准流程

UI 功能流程：

1. 读取配置：config_read("design_system_path")
2. 如果为空，检查：docs/design/design-system.md
3. 如果没有设计系统：先建议使用 Skill("ux-brief")

DevOps 功能流程：

Skill(skill: "majestic-devops:devops-plan")

6. 仓库分析（入门背景）

处理不熟悉的代码库时，在规划功能前收集结构背景信息。

研究领域

领域	检查内容
架构	ARCHITECTURE.md、README.md、CONTRIBUTING.md、CLAUDE.md、AGENTS.md
Issue/PR 模式	.github/PULL_REQUEST_TEMPLATE*、.github/ISSUE_TEMPLATE/
贡献指南	编码标准、测试要求、评审流程
代码库模式	命名约定、模块边界、实现模式

结构分析工具

• 当文本搜索无法满足需求时，通过 Bash 使用 ast-grep 进行语法感知的结构匹配：

  ast-grep --pattern 'class $NAME < ApplicationRecord' --lang ruby
  

• 交叉比对不同来源中的发现
• 优先参考官方文档，而非推断出的模式
• 记录不一致之处或文档缺失

代码库分析输出

## Repository Research Summary

### Architecture & Structure
- Project organization and tech stack
- Key architectural decisions

### Conventions
- Issue/PR formatting and labels
- Coding standards and testing requirements

### Implementation Patterns
- Common code patterns and naming conventions
- Project-specific practices

### Recommendations
- How to align with project conventions
- Areas needing clarification

输出

discovery_result:
  refined_description: string  # Original + refinement context
  refinement_skipped: boolean
  interview_conducted: boolean
  interview_output: string | null  # If interview was run
  acceptance_criteria:
    - criterion: string
      verification: string
  feature_type: "ui" | "devops" | "api" | "data" | "general"
  design_system_path: string | null  # For UI features
  # Research decision signals (for blueprint-research)
  user_familiarity: high | medium | low
  user_intent: speed | thoroughness
  topic_risk: high | medium | low
  uncertainty_level: high | medium | low
  ready_for_research: boolean