design-to-beads

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design to Beads Conversion

设计文档到Beads任务的转换

Overview

概述

Convert design documents into fully-structured beads issues with lossless information transfer, proper epic hierarchy, and validated dependencies.

Core principle: Every piece of actionable content in the source document must map to a beads issue. Nothing gets lost. Dependencies must enable maximum parallelization. Three independent subagent reviews catch what self-review misses.

将设计文档转换为结构完整的beads任务，确保信息无丢失、Epic层级合理且依赖关系经过验证。

核心原则： 源文档中的每一项可执行内容都必须对应一个beads任务，确保无信息遗漏。依赖关系的设置需支持最大程度的并行化。三轮独立的Subagent审核可发现自我审核遗漏的问题。

When to Use

适用场景

Converting finalized design docs to trackable work
Breaking down PRDs into implementation tasks
Creating beads structure from any markdown plan

将定稿的设计文档转换为可追踪的工作任务
将PRD拆解为可落地的实施任务
基于任何Markdown规划文档构建beads任务结构

When NOT to Use

不适用场景

Design isn't finalized (use brainstorming skill first)
Simple single-task work (just create issue directly)

设计文档尚未定稿（请先使用头脑风暴工具）
简单的单一任务（直接创建任务即可）

Critical Rules

关键规则

DO NOT rush under time pressure. Quality conversion takes time. A poorly-structured beads hierarchy causes more delay than taking 30 extra minutes upfront.

DO NOT skip review passes. Single-pass creation misses gaps, creates false dependencies, loses information.

DO NOT self-review. Launch subagents for review passes. Self-review misses what independent reviewers catch.

DO NOT create flat issue lists. Use epics with parent-child relationships.

DO NOT assume sequential ordering. Question every dependency: "Does A truly BLOCK B, or could they run in parallel?"

DO NOT create sparse issues. If the source has detail, the issue must have detail. Brief descriptions = lost information = implementation failures.

切勿因时间仓促而敷衍。 高质量的转换需要时间投入。结构混乱的beads层级比多花30分钟做前期准备造成的延误更大。

切勿跳过审核环节。 单次创建会遗漏信息缺口、设置错误依赖，导致信息丢失。

切勿自我审核。 请启动Subagent进行审核。自我审核无法发现独立审核人员能捕捉到的问题。

切勿创建扁平化任务列表。 请使用带有父子关系的Epic结构。

切勿默认采用顺序执行。 对每一个依赖关系提出质疑：“A是否真的会阻碍B启动，还是两者可以并行执行？”

切勿创建内容稀疏的任务。 如果源文档包含细节，任务中也必须保留对应细节。描述过于简略会导致信息丢失，进而引发实施失败。

The Process

转换流程

Phase 1: Analyze Input Document

第一阶段：分析输入文档

Read the entire document
Identify natural groupings (phases, features, components) → epics
Identify actionable items within each grouping → issues
Note explicit dependencies mentioned in text
Note technical details, acceptance criteria, edge cases

通读整个文档
识别自然分组（阶段、功能、组件）→ Epic
识别每个分组内的可执行项 → 任务
记录文档中明确提及的依赖关系
记录技术细节、验收标准和边缘情况

Phase 2: Draft Structure (DO NOT EXECUTE YET)

第二阶段：草拟任务结构（暂不执行）

Create a written draft:

Epic: [Name]
  - Issue: [Title]
    Dependencies: [list or "none - can start immediately"]
    Key details: [from source doc]

Coverage matrix (REQUIRED):

Source Section → Beads Location
────────────────────────────────
"Phase 1.1 Stripe Setup" → Epic 1, Issue 1.1
"Technical note: 30s timeout" → Issue 1.1 (acceptance criteria)

Every source section MUST appear. Gaps = work not captured = failure.

Detail density tracking (REQUIRED):

Phase/Section     | Source Detail | Beads Detail | Status
──────────────────|───────────────|──────────────|────────
Phase 1 (4 items) | 450 words     | 380 words    | ✓ OK
Phase 2 (6 items) | 600 words     | 120 words    | ⚠️ SPARSE
Phase 3 (3 items) | 200 words     | 190 words    | ✓ OK

Sparse phase = red flag. If beads detail is <50% of source detail, the conversion lost information. Go back and capture missing details before proceeding.

创建书面草稿：

Epic: [Name]
  - Issue: [Title]
    Dependencies: [list or "none - can start immediately"]
    Key details: [from source doc]

覆盖矩阵（必填）：

Source Section → Beads Location
────────────────────────────────
"Phase 1.1 Stripe Setup" → Epic 1, Issue 1.1
"Technical note: 30s timeout" → Issue 1.1 (acceptance criteria)

每一个源文档章节都必须被覆盖。 存在缺口意味着工作未被完整捕捉，属于转换失败。

细节密度跟踪（必填）：

Phase/Section     | Source Detail | Beads Detail | Status
──────────────────|───────────────|──────────────|────────
Phase 1 (4 items) | 450 words     | 380 words    | ✓ OK
Phase 2 (6 items) | 600 words     | 120 words    | ⚠️ SPARSE
Phase 3 (3 items) | 200 words     | 190 words    | ✓ OK

稀疏阶段属于红色预警。 如果beads任务的细节内容不足源文档的50%，说明转换过程中存在信息丢失。返回并补充缺失细节后再继续。

Phase 3: Subagent Review Passes (MANDATORY)

第三阶段：Subagent审核环节（强制要求）

DO NOT self-review. Launch independent subagents for each pass using the Task tool. Self-review is biased; subagents catch what you miss.

If Task tool unavailable: Present full draft to user for manual review at each pass checkpoint. Do NOT substitute self-review for subagent review.

Pass 1: Completeness + Detail Density Review (launch subagent with Task tool)

Subagent mandate:

"Review this beads structure against the source document. Verify: (1) every actionable item has a corresponding issue, (2) every technical note is captured, (3) every acceptance criterion is attached, (4) coverage matrix has no gaps, (5) detail density check: for each phase, compare word count of source vs beads - flag any phase where beads is <50% of source as SPARSE. Report any missing content or sparse phases."

Detail density criteria for each issue:

Description must be substantive (>50 words) OR source item was genuinely simple
Acceptance criteria count should roughly match source complexity
Technical notes from source preserved verbatim, not summarized
If source bullet has sub-bullets, issue must capture them all

Apply fixes from Pass 1 before proceeding.

Pass 2: Dependencies Review (launch subagent)

Subagent mandate:

"Review dependencies in this beads structure. Identify: false sequential ordering (could be parallel), missing blockers, incorrect dependency direction, backward phase dependencies (Phase N task depending on Phase N+M task), over-constrained chains. For each dependency, answer: Does A truly BLOCK B from starting?"

Backward phase dependency = structural error. If a Phase 1 task depends on a Phase 3 task, something is wrong:

The phases are ordered incorrectly in the source document
The task belongs in a different phase
The dependency is incorrect

When backward phase dependencies are found, ask the user: "Should I update the source spec/design document to fix the phase ordering, or should we adjust the task placement?"

Apply fixes from Pass 2 before proceeding.

Pass 3: Clarity + Density Review (launch subagent)

Subagent mandate:

"Review each issue for implementation readiness. Check: title clarity, description completeness, acceptance criteria verifiability. Flag: vague language, assumed knowledge, missing context. Also flag any issue where description is <50 words but the corresponding source section had >100 words - this indicates lost detail. Could a fresh agent execute each issue without referring back to the source document?"

Apply fixes from Pass 3 before proceeding.

Optional Pass 4: Implementation Readiness (for complex projects)

Subagent mandate:

"For each issue: Could a fresh agent with zero codebase context pick this up and execute? Flag: missing file paths, assumed knowledge, vague verbs like 'update the thing'."

切勿自我审核。 使用任务工具启动独立Subagent进行每一轮审核。自我审核存在偏见，Subagent能发现你遗漏的问题。

若任务工具不可用： 在每一轮审核节点将完整草稿提交给用户进行人工审核。切勿用自我审核替代Subagent审核。

第一轮审核：完整性+细节密度审核（通过任务工具启动Subagent）

Subagent任务要求：

"对比源文档审核此beads任务结构。验证：(1) 每一个可执行项都有对应的任务，(2) 每一条技术说明都被捕捉，(3) 每一项验收标准都已关联，(4) 覆盖矩阵无缺口，(5) 细节密度检查：针对每个阶段，对比源文档与beads任务的字数占比——若beads任务字数不足源文档的50%，标记为SPARSE。报告任何缺失内容或稀疏阶段。"

单个任务的细节密度标准：

描述内容必须详实（>50词），或源文档中的对应项确实简单
验收标准的数量应与源文档的复杂度大致匹配
源文档中的技术说明需完整保留，不可简化
若源文档的项目包含子项目，任务中必须完整捕捉所有子项

完成第一轮审核的修复后再进入下一阶段。

第二轮审核：依赖关系审核（启动Subagent）

Subagent任务要求：

"审核此beads任务结构中的依赖关系。识别：错误的顺序设置（本可并行）、缺失的阻塞项、错误的依赖方向、跨阶段反向依赖（第N阶段任务依赖第N+M阶段任务）、过度约束的依赖链。针对每一个依赖关系，回答：A是否真的会阻碍B启动？"

跨阶段反向依赖属于结构错误。 如果第一阶段的任务依赖第三阶段的任务，说明存在问题：

源文档中的阶段顺序设置错误
任务所属阶段不正确
依赖关系设置错误

发现跨阶段反向依赖时，询问用户：“我是否需要更新源规格/设计文档以修正阶段顺序，还是调整任务的所属阶段？”

完成第二轮审核的修复后再进入下一阶段。

第三轮审核：清晰度+密度审核（启动Subagent）

Subagent任务要求：

"审核每个任务的实施就绪度。检查：标题清晰度、描述完整性、验收标准可验证性。标记：模糊表述、默认已知的信息、缺失的上下文。同时标记任何描述内容<50词但对应源文档章节>100词的任务——这表明存在信息丢失。新接手的Agent无需参考源文档即可执行每个任务吗？"

完成第三轮审核的修复后再进入下一阶段。

可选第四轮审核：实施就绪度审核（针对复杂项目）

Subagent任务要求：

"针对每个任务：完全不了解代码库的新Agent能否接手并执行？标记：缺失文件路径、默认已知的信息、模糊动词如'update the thing'。"

Phase 4: User Checkpoint

第四阶段：用户确认节点

Before executing bd commands, present the final structure to the user:

Ready to create:
- X epics
- Y issues
- Z blocking dependencies
- W items ready immediately (parallel start)

Coverage: All N source sections mapped ✓

Detail Density:
  Phase 1: 450 → 380 words (84%) ✓
  Phase 2: 600 → 550 words (92%) ✓
  Phase 3: 200 → 190 words (95%) ✓
  Overall: 1250 → 1120 words (90%) ✓

Proceed with creation? [User must confirm]

If any phase shows <50% density, DO NOT proceed. Go back and flesh out the sparse phases before asking for confirmation.

DO NOT skip this checkpoint. User approval prevents creating wrong structure.

在执行bd命令前，向用户展示最终的任务结构：

准备创建以下内容：
- X个Epic
- Y个任务
- Z个阻塞依赖
- W个可立即启动的任务（并行执行）

覆盖情况：所有N个源文档章节已完成映射 ✓

细节密度：
  第一阶段：450 → 380词（84%） ✓
  第二阶段：600 → 550词（92%） ✓
  第三阶段：200 → 190词（95%） ✓
  整体：1250 → 1120词（90%） ✓

是否继续创建？[需用户确认]

若任何阶段的细节密度<50%，切勿继续。 返回并补充稀疏阶段的内容后再请求用户确认。

切勿跳过此确认节点。 用户确认可避免创建错误的任务结构。

Phase 5: Execute

第五阶段：执行创建

Only after user confirmation:

Create epics first:

bash

bd create "Epic title" -t epic -p <priority> -d "Description"
# Returns: <epic-id>

Create issues with --parent (preferred):

bash

bd create "Issue title" -t task -d "Description" \
  --parent <epic-id> \
  --acceptance "- [ ] Criterion 1"

Backup (when epic ID isn't known at create time):

bash

# bd dep add <child-id> <parent-id> = "child depends on parent"
bd dep add <issue-id> <epic-id> --type parent-child

Add blocker dependencies (only TRUE blockers):

bash

# bd dep add <dependent-id> <prerequisite-id> = "dependent depends on prerequisite"
bd dep add <dependent-id> <prerequisite-id>

Verify:

bash

bd dep cycles          # Must return empty
bd ready --json        # Check expected items ready

仅在用户确认后执行以下操作：

先创建Epic：

bash

bd create "Epic title" -t epic -p <priority> -d "Description"
# Returns: <epic-id>

创建任务并关联父Epic（推荐方式）：

bash

bd create "Issue title" -t task -d "Description" \
  --parent <epic-id> \
  --acceptance "- [ ] Criterion 1"

备选方案（创建时未知Epic ID的场景）：

bash

# bd dep add <child-id> <parent-id> = "child depends on parent"
bd dep add <issue-id> <epic-id> --type parent-child

添加阻塞依赖（仅添加真实阻塞项）：

bash

# bd dep add <dependent-id> <prerequisite-id> = "dependent depends on prerequisite"
bd dep add <dependent-id> <prerequisite-id>

验证：

bash

bd dep cycles          # Must return empty
bd ready --json        # Check expected items ready

Phase 6: Generate Report

第六阶段：生成报告

A. Creation Summary

Created: X epics, Y issues
  Epic 1: [Name] (N issues)
  ...

B. Dependency Graph (show blocking relationships and parallel opportunities)

C. Ready Work Queue (items with no blockers)

D. Coverage Verification

Source sections: N
Mapped to beads: N ✓
Information loss: None

A. 创建总结

已创建：X个Epic，Y个任务
  Epic 1: [Name] (N个任务)
  ...

B. 依赖关系图（展示阻塞关系与并行机会）

C. 就绪任务队列（无阻塞的任务）

D. 覆盖验证

源文档章节数：N
已映射到beads的章节数：N ✓
信息丢失：无

Loophole Closures

常见误区规避

"I'll review it myself to save time" → WRONG. Self-review is biased. Launch subagents.

"The review passes are just a formality" → WRONG. Apply fixes between each pass. Document what changed.

"User checkpoint slows things down" → WRONG. Wrong structure wastes more time. Get confirmation.

"These items obviously need to be sequential" → WRONG. Prove it. State why A must complete before B can START.

"I captured the key points" → WRONG. Capture ALL points. Lossless means lossless.

"This is simple enough for one pass" → WRONG. Even simple docs need review for dependencies.

"Phase 1 legitimately depends on Phase 3" → WRONG. Backward phase dependencies signal incorrect ordering. Ask user if source doc needs updating.

"This phase is simpler, it doesn't need much detail" → WRONG. If the source has detail, capture it. A 600-word source section becoming a 120-word beads issue = 80% information loss. Sparse issues cause implementation failures.

"I'll add more detail when implementing" → WRONG. The beads issue IS the specification. If detail isn't in the issue, it's not in the spec. Capture it now or lose it.

“我自己审核来节省时间” → 错误。自我审核存在偏见，请启动Subagent审核。

“审核环节只是走个形式” → 错误。每轮审核后都要修复问题，并记录修改内容。

“用户确认节点拖慢进度” → 错误。错误的任务结构会浪费更多时间，请务必获取用户确认。

“这些任务显然需要顺序执行” → 错误。请证明必要性，说明A必须在B启动前完成的原因。

“我已经捕捉了关键点” → 错误。要捕捉所有内容，无丢失意味着完全无遗漏。

“这个文档很简单，一轮审核就够了” → 错误。即使是简单文档也需要审核依赖关系。

“第一阶段确实依赖第三阶段” → 错误。跨阶段反向依赖意味着阶段顺序错误，请询问用户是否需要更新源文档。

“这个阶段更简单，不需要太多细节” → 错误。如果源文档包含细节，就必须完整捕捉。600词的源文档章节变成120词的beads任务意味着80%的信息丢失，内容稀疏的任务会导致实施失败。

“我会在实施时补充更多细节” → 错误。beads任务就是实施规格。如果细节不在任务中，就不属于规格内容，请现在就完整捕捉，避免信息丢失。

Common Mistakes

常见错误与修复方案

Mistake	Fix
Flat issue list	Use epics with parent-child
Self-review	Launch subagents
Sequential-by-default	Prove each blocker
Backward phase dependencies	Reorder phases or move task; offer to update source doc
Summarizing details	Preserve exact wording
Sparse descriptions (<50% density)	Compare word counts; flesh out before proceeding
Skipping user checkpoint	Always get confirmation
Rushing for time pressure	Quality over speed

错误	修复方案
扁平化任务列表	使用带有父子关系的Epic结构
自我审核	启动Subagent进行审核
默认顺序执行	验证每个阻塞项的必要性
跨阶段反向依赖	调整阶段顺序或任务所属阶段；询问用户是否需要更新源文档
简化细节	保留源文档的原始表述
内容稀疏的描述（密度<50%）	对比字数占比，补充内容后再继续
跳过用户确认节点	务必获取用户确认
因时间仓促敷衍	质量优先于速度

Quick Reference

快速参考

1. READ entire source document
2. DRAFT structure with coverage matrix
3. SUBAGENT Pass 1: Completeness → Apply fixes
4. SUBAGENT Pass 2: Dependencies → Apply fixes
5. SUBAGENT Pass 3: Clarity → Apply fixes
6. (Optional) SUBAGENT Pass 4: Implementation readiness
7. USER CHECKPOINT: Present structure, get confirmation
8. EXECUTE bd commands (epics → issues → deps)
9. VERIFY no cycles, expected items ready
10. REPORT summary, graph, queue, coverage

Remember: Lossless. Epics. Subagent reviews. User checkpoint. Maximum parallelization.

1. 通读整个源文档
2. 草拟任务结构并制作覆盖矩阵
3. SUBAGENT第一轮审核：完整性 → 修复问题
4. SUBAGENT第二轮审核：依赖关系 → 修复问题
5. SUBAGENT第三轮审核：清晰度 → 修复问题
6. （可选）SUBAGENT第四轮审核：实施就绪度
7. 用户确认节点：展示结构，获取确认
8. 执行bd命令（先创建Epic → 再创建任务 → 最后添加依赖）
9. 验证无循环依赖，确认就绪任务符合预期
10. 生成报告：总结、依赖图、就绪队列、覆盖验证

谨记： 无信息丢失、Epic层级、Subagent审核、用户确认、最大并行化。