playbooks

home / skills / bahayonghang / my-claude-code-settings / spec-interview

spec-interview skill

/content/skills/workflow-skills/spec-interview

This skill conducts structured interviews to refine technical specs from plan.md and auto-generates OpenSpec proposals for spec-driven development.

npx playbooks add skill bahayonghang/my-claude-code-settings --skill spec-interview

Review the files below or copy the command above to add this skill to your agents.

Files (7)
SKILL.md
2.0 KB
---
name: spec-interview
description: 通过系统性访谈完善技术规格文档并生成 spec.md，引导调用平台 Plan 模式落地。适用于需求细化、技术方案设计等场景。
version: 2.0
argument-hint: [plan-or-spec-draft-path]
allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion
category: workflow
tags: [spec, interview, planning, requirements, design, architecture]
---

# 规格访谈

通过苏格拉底式访谈将草稿规格说明转化为完整、可执行的 `spec.md`，然后引导调用平台原生 Plan 模式落地。

## 步骤

1. 若 `$ARGUMENTS` 为空，提示用户提供需求文档路径（默认查找 `plan.md`）。若文件不存在，报错退出。
2. 读取目标文件，分析核心业务目标、方案完整度、模糊/矛盾/缺失点及潜在风险。
3. 读取 `resources/INTERVIEW_PRINCIPLES.md`，按其提问原则进行苏格拉底式访谈。
4. 读取 `resources/INTERVIEW_DIMENSIONS.md`，按 A-G 维度框架逐项向用户提问：
   - 必须覆盖 A（工程原则审查），其余按项目类型选择性覆盖。
   - **必须使用 `AskUserQuestion` 工具**呈现每轮问题，将 2-3 个收敛性选项映射为可点击的交互式选项卡（`options`），禁止以纯文本 A/B/C 形式输出。
   - 每个 `AskUserQuestion` 调用包含 1-4 个问题（`questions`），每个问题 2-4 个选项（`options`），用户可通过 UI 直接点选。
   - 相互独立的问题应合并到同一次 `AskUserQuestion` 调用中，减少交互轮次。
5. 若涉及高风险操作，读取 `resources/RISK_PROTECTION.md` 并发出告警，等待用户明确授权。
6. 访谈完成后，读取 `resources/SPEC_TEMPLATE.md`，按模板汇总生成 `spec.md`（或更新原文件）。
7. 读取 `resources/PLAN_MODE_GUIDE.md`，引导用户启动对应 AI 工具的 Plan 模式执行开发。

## 技术约束

- 路径使用双引号包裹，正斜杠 `/` 分隔
- 优先使用 `rg` 替代 `grep`
- **禁止自动执行** `commit`、`push` 等 Git 写操作
- 遵循 Read-before-Write 原则

Overview

This skill conducts structured, Socratic interviews to turn draft specifications into complete, actionable technical documents and automatically creates an OpenSpec proposal after the interview. It is designed to drive spec-driven development and ensure decisions, risks, and implementation tasks are recorded and ready for execution. The result is a traceable proposal, prioritized tasks, and spec deltas suitable for team review.

How this skill works

The skill reads a provided plan or specification draft, analyzes goals, gaps, and risks, then runs a multi-dimensional interview guided by engineering principles (KISS, YAGNI, DRY, SOLID). It probes architecture, API design, data models, testing, UI/UX, and operational concerns, identifies high-risk operations, and recommends mitigations. After the interview it generates a structured OpenSpec proposal with proposal.md, tasks.md, and spec delta files for clear implementation and review.

When to use it

  • When a draft spec needs clarification before engineering work begins
  • For design reviews and trade-off analysis of technical approaches
  • When preparing a prioritized implementation plan tied to acceptance criteria
  • Before significant infrastructure or schema changes to capture rollback and backup plans
  • To convert informal decisions from meetings into reviewable spec deltas

Best practices

  • Prepare business context and constraints before the interview to speed up deep questioning
  • Answer uncertain items candidly — request option comparisons where you lack a firm choice
  • Follow Read-before-Write: review generated proposal before applying changes
  • Share the generated proposal with stakeholders for early review and alignment
  • Iterate: use follow-up interviews to refine acceptance criteria and tasks

Example use cases

  • Refine a user-management API draft into a production-ready spec with authentication and RBAC decisions
  • Evaluate multiple tech-stack options and produce a trade-off summary and implementation tasks
  • Identify and mitigate risks for a database schema migration with rollback and backup steps
  • Create spec deltas for incremental feature delivery and generate a prioritized task list for sprint planning
  • Audit a design for maintainability, testing strategy, and adherence to SOLID/DRY principles

FAQ

What outputs will I get after the interview?

You receive a structured OpenSpec proposal containing a proposal summary, prioritized tasks, and spec delta files that mark additions, modifications, and deletions.

How does the skill detect high-risk operations?

It identifies operations like file deletion, force-push, env var changes, schema migrations, and bulk dependency updates, then provides impact descriptions, rollback steps, backup strategies, and testing guidance.

Can I iterate on the generated proposal?

Yes. The proposal is intended for review and refinement; you can run follow-up interviews to expand details, adjust priorities, and update acceptance criteria.