Back to Details

complete-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Complete Specification (with GitHub Spec Kit)

完善规范文档（借助GitHub Spec Kit）

Step 5 of 6 in the Reverse Engineering to Spec-Driven Development process.
Estimated Time: 30-60 minutes (interactive) Prerequisites: Step 4 completed (
docs/gap-analysis-report.md
exists with clarifications list) Output: Updated specs in 
specs/
with all 
[NEEDS CLARIFICATION]
markers resolved
这是「从逆向工程到规范驱动开发」流程6个步骤中的第5步。
预计耗时： 30-60分钟（交互式） 前置条件： 已完成第4步（存在
docs/gap-analysis-report.md
，包含待澄清事项列表） 输出结果： 
specs/
目录下的规范文档已更新，所有
[NEEDS CLARIFICATION]
标记均已解决

When to Use This Skill

何时使用该技能

Use this skill when:
  • You've completed Step 4 (Gap Analysis)
  • Have 
    [NEEDS CLARIFICATION]
    markers in specifications
  • Ready for interactive clarification session using 
    /speckit.clarify
  • Want to finalize specifications before implementation
Trigger Phrases:
  • "Complete the specification"
  • "Resolve clarifications"
  • "Run speckit clarify"
  • "Let's clarify the missing details"
在以下场景使用本技能：
  • 已完成第4步（差距分析）
  • 规范文档中存在
    [NEEDS CLARIFICATION]
    标记
  • 准备好使用
    /speckit.clarify
    进行交互式澄清会话
  • 希望在开发前最终确定规范文档
触发语：
  • "完善规范文档"
  • "解决待澄清事项"
  • "运行speckit clarify"
  • "我们来澄清缺失的细节"

What This Skill Does

本技能的作用

Uses 
/speckit.clarify
and interactive conversation to fill specification gaps:
  1. Use /speckit.clarify - GitHub Spec Kit's built-in clarification tool
  2. Interactive Q&A - Ask questions about missing features and details
  3. Update Specifications - Add answers to specs in 
    specs/
  4. Resolve Ambiguities - Remove all 
    [NEEDS CLARIFICATION]
    markers
  5. Update Implementation Plans - Refine plans in 
    specs/
  6. Finalize for Implementation - Ready for 
    /speckit.tasks
    and 
    /speckit.implement
Note: 
/speckit.clarify
provides structured clarification workflow. This skill can also supplement with custom Q&A for project-specific needs.
通过
/speckit.clarify
和交互式对话填补规范文档中的空白：
  1. 使用/speckit.clarify - GitHub Spec Kit内置的澄清工具
  2. 交互式问答 - 针对缺失的功能和细节提出问题
  3. 更新规范文档 - 将答案添加到
    specs/
    目录下的规范中
  4. 消除歧义 - 移除所有
    [NEEDS CLARIFICATION]
    标记
  5. 更新实施计划 - 优化
    specs/
    目录下的计划
  6. 为开发就绪 - 可进入
    /speckit.tasks
    和
    /speckit.implement
    环节
注意： 
/speckit.clarify
提供结构化的澄清工作流。本技能还可补充自定义问答，以满足项目特定需求。

Process Overview

流程概述

Step 1: Collect All Clarifications

步骤1：收集所有待澄清事项

From 
specs/gap-analysis.md
and all feature specs:
  • List all 
    [NEEDS CLARIFICATION]
    markers
  • Group by feature
  • Prioritize by impact (P0 first)
从
specs/gap-analysis.md
和所有功能规范中：
  • 列出所有
    [NEEDS CLARIFICATION]
    标记
  • 按功能分组
  • 按影响优先级排序（优先处理P0级事项）

Step 2: Interactive Q&A Session

步骤2：交互式问答会话

For each clarification, ask the user:
Example questions:
  • "The Analytics Dashboard feature is missing. What charts/metrics should be displayed?"
  • "For photo upload, should it be drag-and-drop or click-to-browse?"
  • "Should offline sync download full data or just metadata?"
  • "What's the maximum number of photos per fish?"
  • "For species input, free-text field or autocomplete dropdown?"
Listen for:
  • Feature requirements
  • UX/UI preferences
  • Business logic rules
  • Constraints and limitations
  • Priority adjustments
针对每个待澄清事项，向用户提问：
示例问题：
  • "Analytics Dashboard功能缺失，应展示哪些图表和指标？"
  • "对于照片上传功能，应采用拖拽上传还是点击浏览上传？"
  • "离线同步应下载完整数据还是仅元数据？"
  • "每条鱼最多可上传多少张照片？"
  • "物种输入应使用自由文本字段还是自动补全下拉框？"
需收集的信息：
  • 功能需求
  • UX/UI偏好
  • 业务逻辑规则
  • 约束条件与限制
  • 优先级调整

Step 3: Update Feature Specs

步骤3：更新功能规范

As user answers questions:
  • Add details to feature specs
  • Define acceptance criteria
  • Specify UI behavior
  • Document business rules
  • Remove 
    [NEEDS CLARIFICATION]
    markers
在用户回答问题时：
  • 为功能规范补充细节
  • 定义验收标准
  • 明确UI行为
  • 记录业务规则
  • 移除
    [NEEDS CLARIFICATION]
    标记

Step 4: Confirm Priorities

步骤4：确认优先级

Review the prioritized implementation plan:
  • Are P0 items truly critical?
  • Should any features move up/down in priority?
  • What's the target timeline?
审查已排序的实施计划：
  • P0级事项是否确实至关重要？
  • 是否有功能需要调整优先级？
  • 目标时间线是什么？

Step 5: Finalize Specifications

步骤5：最终确定规范文档

Ensure all specs are:
  • Complete (no clarification markers)
  • Unambiguous (clear requirements)
  • Testable (acceptance criteria defined)
  • Prioritized (P0/P1/P2/P3)
确保所有规范文档：
  • 完整（无待澄清标记）
  • 无歧义（需求清晰）
  • 可测试（已定义验收标准）
  • 已排序（P0/P1/P2/P3）

Example Interactive Session

交互式会话示例

Claude:
I found 12 items that need clarification. Let me go through them by priority.
F003 - Analytics Dashboard [P1] This feature is marked as missing. What specific charts and metrics should be displayed?
User:
I want to see:
  • Fish count over time (line chart)
  • Water parameter trends (multi-line chart)
  • Tank health score (gauge)
  • Recent alerts (list)
Claude:
Got it! I'll add those requirements to F003.
Should these be real-time updates or daily aggregates?
User:
Daily aggregates for the charts, but real-time for alerts.
Claude:
Perfect. Next question:
F002 - Photo Upload UI [P0] For uploading fish photos, would you prefer drag-and-drop or click-to-browse?
User:
Both options would be ideal.
Claude:
Understood. What's the maximum number of photos per fish?
User:
Let's limit it to 10 photos per fish.
[...continues for all clarifications...]
Claude：
我发现有12项待澄清事项，我将按优先级依次处理。
F003 - Analytics Dashboard [P1] 该功能标记为缺失，应展示哪些具体的图表和指标？
用户：
我希望看到：
  • 鱼类数量随时间变化的折线图
  • 水质参数趋势的多折线图
  • 鱼缸健康评分仪表盘
  • 近期告警列表
Claude：
明白了！我会将这些需求添加到F003中。
这些数据应实时更新还是按日聚合？
用户：
图表采用日聚合数据，但告警需实时更新。
Claude：
好的。下一个问题：
F002 - 照片上传UI [P0] 对于鱼类照片上传，你偏好拖拽上传还是点击浏览上传？
用户：
两种选项都要有最好。
Claude：
理解。每条鱼最多可上传多少张照片？
用户：
限制为每条鱼最多10张照片。
[...所有待澄清事项依次处理...]

Output Updates

输出更新内容

Updated Feature Specs

更新后的功能规范

Before:
markdown
undefined
更新前：
markdown
undefined

Analytics Dashboard [NEEDS CLARIFICATION]

Analytics Dashboard [NEEDS CLARIFICATION]

Status: ❌ MISSING
[NEEDS CLARIFICATION] What charts and metrics to display?

**After:**
```markdown
Status: ❌ MISSING
[NEEDS CLARIFICATION] 应展示哪些图表和指标？

**更新后：**
```markdown

Analytics Dashboard

Analytics Dashboard

Status: ❌ MISSING Priority: P1
Status: ❌ MISSING Priority: P1

Overview

概述

Dashboard displaying fish count trends, water parameter history, tank health, and recent alerts.
展示鱼类数量趋势、水质参数历史、鱼缸健康状态和近期告警的仪表盘。

Acceptance Criteria

验收标准

  • Fish count over time line chart (daily aggregates)
  • Water parameter trends multi-line chart (pH, temp, ammonia)
  • Tank health score gauge (0-100)
  • Recent alerts list (real-time updates)
  • Date range selector (7d, 30d, 90d, all)
  • 鱼类数量随时间变化的折线图（日聚合）
  • 水质参数趋势多折线图（pH值、温度、氨含量）
  • 鱼缸健康评分仪表盘（0-100分）
  • 近期告警列表（实时更新）
  • 日期范围选择器（7天、30天、90天、全部）

UI Requirements

UI要求

  • Responsive design (desktop + mobile)
  • Charts use Recharts library
  • Real-time updates for alerts via WebSocket
  • 响应式设计（桌面端 + 移动端）
  • 图表使用Recharts库
  • 告警通过WebSocket实现实时更新

API Requirements

API要求

  • GET /api/analytics/fish-count?range=30d
  • GET /api/analytics/water-params?range=30d
  • GET /api/analytics/health-score
  • WebSocket /ws/alerts for real-time alerts
undefined
  • GET /api/analytics/fish-count?range=30d
  • GET /api/analytics/water-params?range=30d
  • GET /api/analytics/health-score
  • WebSocket /ws/alerts 用于实时告警
undefined

Updated Gap Analysis

更新后的差距分析报告

Remove resolved clarifications from the list.
从列表中移除已解决的待澄清事项。

Updated Implementation Status

更新后的实施状态

Reflect finalized priorities and details.
反映最终确定的优先级和细节。

Success Criteria

成功标准

After running this skill, you should have:
  • ✅ All 
    [NEEDS CLARIFICATION]
    markers resolved
  • ✅ Feature specs updated with complete details
  • ✅ Acceptance criteria defined for all features
  • ✅ Priorities confirmed (P0/P1/P2/P3)
  • ✅ Implementation roadmap finalized
  • ✅ Ready to proceed to Step 6 (Implement from Spec)
运行本技能后，你应获得：
  • ✅ 所有
    [NEEDS CLARIFICATION]
    标记均已解决
  • ✅ 功能规范已更新，包含完整细节
  • ✅ 所有功能均已定义验收标准
  • ✅ 优先级已确认（P0/P1/P2/P3）
  • ✅ 实施路线图已最终确定
  • ✅ 可进入第6步（依据规范开发）

Next Step

下一步

Once specifications are complete and unambiguous, proceed to:
Step 6: Implement from Spec - Use the implement skill to systematically build missing features.
一旦规范文档完整且无歧义，即可进入：
第6步：依据规范开发 - 使用开发技能系统性地构建缺失的功能。

Interactive Guidelines

交互式指南

Asking Good Questions

提出优质问题

DO:
  • Ask specific, focused questions
  • Provide context for each question
  • Offer examples or common patterns
  • Ask one category at a time (don't overwhelm)
  • Confirm understanding by summarizing
DON'T:
  • Ask overly technical questions (keep user-focused)
  • Assume answers (always ask)
  • Rush through clarifications
  • Mix multiple questions together
建议：
  • 提出具体、聚焦的问题
  • 为每个问题提供上下文
  • 提供示例或常见模式
  • 一次询问一个类别（避免使用户不知所措）
  • 通过总结确认理解
避免：
  • 提出过于技术化的问题（以用户为中心）
  • 假设答案（务必询问）
  • 仓促完成澄清过程
  • 混合多个问题

Handling Uncertainty

处理不确定性

If user is unsure:
  • Suggest common industry patterns
  • Provide examples from similar features
  • Offer to defer to later (mark as P2/P3)
  • Document the uncertainty and move on
如果用户不确定：
  • 建议行业通用模式
  • 提供类似功能的示例
  • 提议延后处理（标记为P2/P3）
  • 记录不确定性并继续推进

Documenting Answers

记录答案

For each answer:
  • Update the relevant feature spec immediately
  • Add to acceptance criteria
  • Remove clarification marker
  • Confirm understanding with user
对于每个答案：
  • 立即更新相关的功能规范
  • 添加到验收标准中
  • 移除待澄清标记
  • 与用户确认理解无误

Technical Notes

技术说明

  • Ask questions conversationally and collect answers through natural dialogue
  • Group related questions together
  • Prioritize P0 clarifications first
  • Keep a running list of resolved items
  • Update specs incrementally (don't batch)
Remember: This is Step 5 of 6. After this interactive session, you'll have complete, unambiguous specifications ready for implementation in Step 6.
  • 以对话方式提出问题，通过自然对话收集答案
  • 将相关问题分组
  • 优先处理P0级待澄清事项
  • 维护已解决事项的动态列表
  • 逐步更新规范（不要批量处理）
注意： 这是6个步骤中的第5步。完成本次交互式会话后，你将获得完整、无歧义的规范文档，为第6步的开发工作做好准备。