spec-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SKILL: spec-init

Overview

概述

Unified skill that guides spec creation through structured, interactive process.

Wraps these existing skills:

progressive-disclosure (requirements gathering)
spec-validator (schema validation)
plan-generator (plan from spec)

一款统一的Skill，通过结构化、交互式流程指导规格说明书的创建。

它封装了以下现有Skill：

progressive-disclosure（需求收集）
spec-validator（Schema 验证）
plan-generator（基于规格生成计划）

Workflow

工作流

1. Type Detection

1. 类型检测

Question: "What are you building?"

Auto-detect from description:

Feature: "Build X functionality" →
```
type: feature
```
Bug: "Fix X issue" →
```
type: bug
```
Chore: "Update X component" →
```
type: chore
```
Refactor: "Reorganize X" →
```
type: refactor
```
Docs: "Document X" →
```
type: docs
```

问题：「你要构建什么？」

根据描述自动检测：

功能：「构建X功能」→
```
type: feature
```
缺陷：「修复X问题」→
```
type: bug
```
杂务：「更新X组件」→
```
type: chore
```
重构：「重组X」→
```
type: refactor
```
文档：「编写X文档」→
```
type: docs
```

2. Progressive Disclosure v2 (Adaptive, 5-7 questions)

2. 渐进式信息收集 v2（自适应，5-7个问题）

Invoke progressive-disclosure with adaptive algorithm:

javascript

const { AdaptiveQuestioner } = require('.claude/lib/utils/adaptive-discloser.cjs');
const { ContextAccumulator } = require('.claude/lib/utils/context-accumulator.cjs');

// Determine domain from detected type
const domainMap = {
  feature: 'general',
  bug: 'debugging',
  chore: 'general',
  refactor: 'architecture',
  docs: 'documentation',
};
const domain = domainMap[detectedType] || 'general';

const aq = new AdaptiveQuestioner(domain);
const ca = new ContextAccumulator();

let history = [];
let questionCount = 0;

while (questionCount < 7) {
  const context = ca.getContext();
  const result = await aq.getNextQuestion(context, history);

  // Check if we should stop early
  const readiness = await aq.detectOptimalStop(history, context);
  if (readiness.shouldStop) {
    break;
  }

  // Ask the question
  const answer = await AskUserQuestion({ question: result.question });

  // Store answer with metadata
  ca.addAnswer(result.question, answer, { domain, priority: 'HIGH' });
  history.push({ question: result.question, answer });

  questionCount++;
}

// Summary from accumulated context
const summary = ca.buildSummary();

Key Improvements over v1:

Adaptive questioning (skips redundant questions)
Context-aware (learns from answers)
Memory-integrated (leverages learnings.md)
Optimal stopping (5-7 questions typical, down from 10-12)
Quality scoring (detects when ready for spec generation)

调用带有自适应算法的progressive-disclosure：

javascript

const { AdaptiveQuestioner } = require('.claude/lib/utils/adaptive-discloser.cjs');
const { ContextAccumulator } = require('.claude/lib/utils/context-accumulator.cjs');

// Determine domain from detected type
const domainMap = {
  feature: 'general',
  bug: 'debugging',
  chore: 'general',
  refactor: 'architecture',
  docs: 'documentation',
};
const domain = domainMap[detectedType] || 'general';

const aq = new AdaptiveQuestioner(domain);
const ca = new ContextAccumulator();

let history = [];
let questionCount = 0;

while (questionCount < 7) {
  const context = ca.getContext();
  const result = await aq.getNextQuestion(context, history);

  // Check if we should stop early
  const readiness = await aq.detectOptimalStop(history, context);
  if (readiness.shouldStop) {
    break;
  }

  // Ask the question
  const answer = await AskUserQuestion({ question: result.question });

  // Store answer with metadata
  ca.addAnswer(result.question, answer, { domain, priority: 'HIGH' });
  history.push({ question: result.question, answer });

  questionCount++;
}

// Summary from accumulated context
const summary = ca.buildSummary();

相较于v1的关键改进：

自适应提问（跳过冗余问题）
上下文感知（从答案中学习）
集成记忆功能（基于learnings.md）
最优停止机制（通常5-7个问题，相较于之前的10-12个有所减少）
质量评分（检测是否已准备好生成规格说明书）

3. Spec Template Generation

3. 规格说明书模板生成

Auto-populate spec from answers:

markdown

undefined

根据答案自动填充规格说明书：

markdown

undefined

SPEC: [Feature Name]

1. Overview

1. 概述

Title: [From question 1] Type: [Detected type] Objective: [User summary]

User Story: As a [user type], I want [capability], so that [benefit]

Acceptance Criteria: [From question 5]

标题：[来自问题1的答案] 类型：[检测到的类型] 目标：[用户总结]

用户故事：作为[用户角色]，我希望[具备某项能力]，以便[获得某种收益]

验收标准：[来自问题5的答案]

2. Problem Statement

2. 问题陈述

Current State: [From question 1 answers]
Pain Points: [Extracted from answers]
Impact: [Quantified if possible]

当前状态：[来自问题1的答案]
痛点：[从答案中提取]
影响：[尽可能量化]

3. Proposed Solution

3. 提议的解决方案

Approach: [From user input]
Key Features: [From answers]
Scope: [What's in/out]

实现思路：[来自用户输入]
核心功能：[来自答案]
范围：[包含/排除的内容]

4. Implementation Approach

4. 实施步骤

Phase 1: [Design/spike if needed]
Phase 2: [Core implementation]
Phase 3: [Testing]
Phase 4: [Documentation]

阶段1：[如有需要，进行设计/调研]
阶段2：[核心功能实现]
阶段3：[测试]
阶段4：[文档编写]

5. Success Metrics

5. 成功指标

Quantitative: [From question 3]
Qualitative: [User satisfaction]
Timeline: [From question 4]

量化指标：[来自问题3的答案]
定性指标：[用户满意度]
时间线：[来自问题4的答案]

6. Effort Estimate

6. 工作量估算

Design: 1 day
Implementation: 3 days
Testing: 2 days
Documentation: 1 day
Total: 7 days

设计：1天
实现：3天
测试：2天
文档：1天
总计：7天

7. Dependencies

7. 依赖项

Required: [Extracted from context]
Blocking: [What must complete first]
Risk: [Key risks identified]

必需项：[从上下文中提取]
阻塞项：[必须先完成的任务]
风险：[已识别的关键风险]

8. Acceptance Criteria Checklist

8. 验收标准检查清单

4. Validation

4. 验证

Validate spec against schema:

Invoke spec-validator skill
Check: all required sections present
Check: at least 3 acceptance criteria
Check: effort estimate in days

根据Schema验证规格说明书：

调用spec-validator Skill
检查：所有必填章节是否存在
检查：至少包含3条验收标准
检查：工作量估算以天为单位

5. Plan Suggestion

5. 计划建议

After spec approved:

Suggest: "Ready for planner to create plan?"

If yes: Show

Skill({ skill: "plan-generator", args: { specPath: "..." } })

If no: Allow editing spec

规格说明书获批后：

询问：「是否准备好使用计划生成器创建计划？」

如果是：展示

Skill({ skill: "plan-generator", args: { specPath: "..." } })

如果否：允许编辑规格说明书

6. Storage

6. 存储

Save spec to:

.claude/context/artifacts/specs/[feature-name]-spec-YYYYMMDD.md

Track metadata:

trackId: auto-generated
type: detected
status: "new"
created_at: timestamp

将规格说明书保存至：

.claude/context/artifacts/specs/[feature-name]-spec-YYYYMMDD.md

跟踪元数据：

trackId：自动生成
type：检测到的类型
status："new"
created_at：时间戳

Usage Examples

使用示例

Example 1: Quick Feature

示例1：快速创建功能规格

User: "I want to add dark mode to the UI"

spec-init workflow:
1. Detect: type = "feature"
2. Ask: 5 questions about dark mode
3. User answers in <5 minutes
4. Generate spec
5. Validate against schema
6. Store and offer plan generation

用户：「我想给UI添加深色模式」

spec-init 工作流：
1. 检测：类型 = "feature"
2. 提问：关于深色模式的5个问题
3. 用户在5分钟内完成回答
4. 生成规格说明书
5. 按Schema验证
6. 存储并提供计划生成选项

Example 2: Bug Fix

示例2：缺陷修复规格

User: "There's a memory leak in the scheduler"

spec-init workflow:
1. Detect: type = "bug"
2. Ask: 5 questions (reproduce steps, impact, etc)
3. Generate bug fix spec
4. Suggest acceptance criteria
5. Ready for planner

用户：「调度器存在内存泄漏问题」

spec-init 工作流：
1. 检测：类型 = "bug"
2. 提问：5个问题（重现步骤、影响等）
3. 生成缺陷修复规格说明书
4. 建议验收标准
5. 准备好进入计划生成环节

Output

输出

Generated spec markdown (saved)
Track metadata JSON
Plan generation suggestion
Next steps guidance

生成的规格说明书Markdown文件（已保存）
跟踪元数据JSON
计划生成建议
下一步操作指引

Integration Points

集成点

progressive-disclosure (requirements gathering)
spec-validator (schema validation)
plan-generator (next step)
track-metadata schema (metadata)

progressive-disclosure（需求收集）
spec-validator（Schema 验证）
plan-generator（下一步）
track-metadata schema（元数据）

Memory Protocol (MANDATORY)

记忆协议（强制性要求）

Before starting: Read

.claude/context/memory/learnings.md

After completing:

New pattern ->
```
.claude/context/memory/learnings.md
```
Issue found ->
```
.claude/context/memory/issues.md
```
Decision made ->
```
.claude/context/memory/decisions.md
```

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

开始前：读取

.claude/context/memory/learnings.md

完成后：

新模式 → 写入
```
.claude/context/memory/learnings.md
```
发现问题 → 写入
```
.claude/context/memory/issues.md
```
决策记录 → 写入
```
.claude/context/memory/decisions.md
```

假设可能被中断：如果未存入记忆，则视为未发生。