SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdefine-workflow-spec

define-workflow-spec

Office & productivity

View repository

Updated 10-16 09:45

About this skill

Spec — Specification Writing

Entry/Exit

  • Entry: define-workflow-refine complete, user has approved direction
  • Exit: docs/features/YYYYMMDD-<name>/01-spec.md + user approval
  • Points to: after user approves spec, preferentially invoke design-workflow-design; pure backend/script/migration can skip to build-workflow-plan
  • Output path: → design-workflow-design or build-workflow-plan (pure backend/script/migration)
  • Preload: CANON.md (optionally load build-cognitive-decision-record/SKILL.md — load again when there are architectural decisions)

When not to use

  • Single-line fixes, typos, changes with clear and self-contained requirements
  • Pure configuration changes, dependency upgrades, and other changes that require no design decisions

Process

Step 1：Surface Assumptions

Before writing any spec content, first list assumptions:

ASSUMPTIONS I'M MAKING:
1. 这是 Web 应用（不是原生移动端）
2. 认证使用 session cookie（不是 JWT）
3. 数据库是 PostgreSQL（基于现有 Prisma schema）
4. 目标现代浏览器（不支持 IE11）
→ 现在纠正我，否则我按这些继续。

Do not silently fill in ambiguous requirements. The entire value of a spec lies inbefore writing codeexposing misunderstandings.

Step 2: Write the spec document

Cover the following content:

  1. Objective — what to build, why, for whom, success criteria
  2. Artifact Type — deliverable type. Default software; optional software / document / article / deck / visual
  3. Goal Alignment — goal source, target quality state, Done When and Stop Conditions. It is the source/quality summary of the spec,not /goal a substitute for lifecycle management.
  4. Commands / Tools — complete executable commands or artifact tools (including parameters): 
    Build: npm run build
Test: npm test -- --coverage
Lint: npm run lint --fix
Dev: npm run dev
  5. Project Structure / Artifact Paths — source code, tests, documentation, or final artifact paths
  6. Style / Quality Bar — code style, writing style, layout, visual style, or presentation standards
  7. Verification Strategy — testing, fact-checking, layout checking, export checking, or manual acceptance methods
  8. Documentation Impact — document slots and project-level sync intent:
    • doc_intent: feature_only | feature_plus_project | project_only
    • project_truth_changed: yes | no
    • affected_project_docs: explicitly list README.md、AGENTS.md、CHANGELOG.md、DESIGN.md or docs/architecture/*.md
    • rationale: why only write feature docs, or why project docs must be synced
  9. Boundaries (three-level system):
    • Always do: run tests before committing, follow naming conventions, validate inputs
    • Ask first: database schema changes, adding dependencies, modifying CI configuration
    • Never do: committing secrets, editing the vendor directory, deleting failing tests without approval

spec template:

# Spec: [功能名称]

## Objective
[构建什么、为什么。用户故事或验收条件。]

## Artifact Type
artifact_type: software

Allowed: software / document / article / deck / visual

## Goal Alignment
- Source Goal: conversation / `GOAL.md`
- Goal Status: accepted / needs-refinement / blocked
- Goal Review Score: <score>/12

### One-line Goal
[一句话目标]

### Done When
- [ ] Functional:
- [ ] Technical:
- [ ] Regression:
- [ ] Output:

### Stop Conditions
- [ ] Acceptance 无法验证
- [ ] 需要修改明确排除范围
- [ ] 需要改变 API / 权限 / 数据结构 / 生产配置
- [ ] 实际范围明显大于当前 Goal

## Documentation Impact
- doc_intent: feature_only
- project_truth_changed: no
- affected_project_docs:
  - none
- rationale:

## Tech Stack
[software 时填写框架、语言、关键依赖；非 software 时填写工具链、格式、模板或品牌约束]

## Commands / Tools
[Build, test, lint, dev，或 DOCX/PPTX/PDF/PNG/SVG 导出工具与命令]

## Project Structure / Artifact Paths
[目录布局、源文件路径、最终交付物路径]

## Style / Quality Bar
[代码约定，或文风、叙事、版式、视觉标准]

## Verification Strategy
[自动测试、事实核查、人工审查、版式检查、导出验证]

## Documentation Impact
[默认 `feature_only`。当公共 API / CLI / 启动方式 / 部署配置 / 跨 feature 设计约束 / 系统边界 / 监控安全规则变化时，升级为 `feature_plus_project` 或 `project_only`，并明确列出受影响的项目级文档路径。]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[如何判定"做完"——具体、可测试的条件]

`Done When` 是 goal 级完成定义；`Success Criteria` 是 spec 级验收标准。两者必须一致，不能出现 Done When 说完成但 Success Criteria 无法验证的情况。

## Risks and Mitigations
| 风险 | 概率 | 影响 | 应对方案 |
|------|------|------|---------|
| [风险] | [高/中/低] | [高/中/低] | [策略] |

## Open Questions
[需要用户输入的未解决问题]

Step 3: Convert ambiguous requirements into acceptance conditions

When receiving ambiguous requirements, translate them into specific testable conditions:

REQUIREMENT: "让仪表盘更快"

REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s（4G 网络）
- 初始数据加载 < 500ms
- 加载时无布局偏移（CLS < 0.1）
→ 这些目标对吗？

Step 4: User review

After the spec is written → ask the user to review the spec file → confirm or modify → proceed to plan only after user approval.

Validation failure handling

Failure scenario Handling method
User rejects spec Return to define-workflow-refine Phase 1, get clarification and rewrite the spec. Do not directly proceed by modifying the rejected spec.
User requests major modifications Modify directly on the spec file, and repeat the user review step. User approval is still required after modification.
Requirement change Update the spec; no need to refine again. But if the change involves Goal Alignment, Goal Review must be redone.
spec lacks Success Criteria Force the inclusion of specific, testable acceptance criteria. Abstract descriptions (such as "better" or "faster") cannot replace quantified standards.
project_truth_changed: yes but missing affected_project_docs blocking. The project-level document paths to be synchronized must be explicitly written out; you cannot write "add documentation later."
Goal Alignment conflicts with Success Criteria Mark as Blocking, and prioritize fixing Done When or Success Criteria to make them consistent.
Hidden assumptions are not listed in Surface Assumptions Go back to Step 1 and add the missing assumptions. Do not proceed to spec writing with unlisted assumptions.

Verification Evidence

The output or record must include:

  • Input/Source: The spec, plan, code, feedback, or release context that was read.
  • Actions Performed: The actual checks, generation, fixes, exports, or release steps completed.
  • Verification Results: Commands, review conclusions, artifact paths, screenshots, or manual confirmation.
  • Blocking/Rollback: Failed items, rollback paths, or issues requiring a human partner's decision.

Common Excuses

Excuse Reality Consequence
"This is simple and doesn't need a spec" Simple tasks don't need a long spec, but acceptance criteria are still required. A two-line spec is enough. Simple tasks without a spec miss an average of 1-2 acceptance criteria, which surface as bugs after launch.
"Write the spec after writing the code" That's documentation, not a specification. The value of a spec lies in clarifying requirements before writing code. A spec written after the fact conforms to the behavior already implemented rather than to the requirements, and missed edge cases become permanently locked in.
"A spec will slow us down" A 15-minute spec prevents hours of rework. A 15-minute waterfall is faster than 15 hours of debugging. Skipping the spec and coding directly typically causes 1-2 rounds of rework, each taking 4-8 hours, for a total time > 10-20x that of the spec process.

Red Flags

  • Starting to write spec content before Surface Assumptions
  • The spec lacks Success Criteria (success standards are not specific = cannot be accepted)
  • The spec lacks Goal Alignment (cannot trace the source of the goal or the definition of done)
  • The spec lacks Documentation Impact (cannot determine which layer the documentation should go to)
  • Goal Alignment conflicts with Success Criteria
  • project_truth_changed: yes but no affected_project_docs
  • The "not-doing list" has no explicit trade-off
  • A spec already approved by the user is silently changed during implementation
  • Skipping user review and going directly to design / plan
  • Architecture decision is not recorded

Verification Checklist

  • The spec covers all 9 core areas
  • artifact_type has been declared; when not declared, explicitly treat it as software handling
  • Goal Alignment has been declared, and Done When is consistent with Success Criteria
  • Documentation Impact has been declared; when project docs need to be synchronized, explicit paths have been listed
  • Stop Conditions have been declared
  • Hidden assumptions have been listed (Surface Assumptions)
  • The user has reviewed and approved the spec
  • Success criteria are specific and testable
  • Boundaries (Always/Ask First/Never) have been defined
  • Risks and mitigation plans have been evaluated
  • spec has been saved to docs/features/YYYYMMDD-<name>/01-spec.md

Good and bad examples

Good — from vague requirements to quantified acceptance

用户: "让仪表盘更快"

Step 1 Surface Assumptions:
ASSUMPTIONS I'M MAKING:
1. 当前 LCP > 5s（需验证）
2. 用户主要在 4G 网络使用
3. 首屏数据来自 3 个 API
→ 现在纠正我

Step 3 转化:
REQUIREMENT: "让仪表盘更快"
REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s（4G 网络）
- 初始数据加载 < 500ms
- 加载时无布局偏移（CLS < 0.1）

→ 量化验收条件替代模糊描述，spec 可验证

Bad — vague description goes directly into implementation

用户: "让仪表盘更快"

（跳过 Surface Assumptions，跳过 Step 3 转化）

spec: "优化仪表盘性能，让页面更快"

→ 问题: 没有量化标准 → 无法验收 → "更快"无法判定是否完成
→ 问题: 没有列出假设 → 优化方向基于猜测而非数据 → 可能优化了不重要的瓶颈
→ 问题: Success Criteria 和 Done When 无法一致 → Goal Review 失败

Output template

### Spec 交付记录 — <feature-name>

**artifact_type**: [software / document / article / deck / visual]
**Goal Alignment**: [来源 / 状态 / 评分]
**Done When**: [具体可验证条件]
**Stop Conditions**: [具体阻断条件]
**Documentation Impact**: [doc_intent / project_truth_changed / affected_project_docs]

**核心区域覆盖**:
- Objective: ✓ / ✗
- Artifact Type: ✓ / ✗
- Goal Alignment: ✓ / ✗
- Documentation Impact: ✓ / ✗
- Commands / Tools: ✓ / ✗
- Project Structure: ✓ / ✗
- Style / Quality Bar: ✓ / ✗
- Verification Strategy: ✓ / ✗
- Boundaries: ✓ / ✗

**Surface Assumptions**: [已列出 / 未列出]
**用户批准**: [已批准 / 待批准]