to-tickets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

To Tickets

生成工单

Break plan/spec/conversation into tickets — tracer-bullet vertical slices, each declaring tickets that block it. Publish per consumer repo's tracker conventions (AGENTS.md).

将计划/规格说明/对话拆分为工单——即tracer-bullet垂直切片，每个工单需声明其依赖阻塞的其他工单。按照目标仓库的追踪器规范（AGENTS.md）发布工单。

Reproducibility invariant

可复现性准则

Full issue set, replayed in dependency order — features and bugfixes alike — must build roughly same application, regardless of who or what implements.

Issue stream = buildable spec. Every rule below serves this.

完整的工单集合，按依赖顺序执行——无论是功能开发还是Bug修复——无论由谁或什么工具实现，都必须构建出基本一致的应用程序。

工单流 = 可构建的规格说明。以下所有规则均为此目标服务。

Self-containedness

自包含性

Every outcome-shaping decision lives in issue itself, or durable docs it references — ADRs (

writing-adrs

), glossary terms (

docs/glossary/

). Never conversation context, tribal knowledge, implementer discretion.

Litmus test: two independent implementers could build meaningfully different things → ticket underspecified. Add decision to ticket, or record as ADR/glossary term + reference.

所有影响结果的决策都必须记录在工单本身中，或在其引用的持久化文档里——比如ADRs（

writing-adrs

）、术语表条目（

docs/glossary/

）。绝不能依赖对话上下文、隐性经验或实现者的主观判断。

验证测试： 如果两名独立的实现者能构建出差异显著的结果 → 说明工单的规格说明不充分。需将相关决策补充到工单中，或记录为ADR/术语表条目并在工单中引用。

Bugfixes = spec corrections

Bug修复 = 规格说明修正

Never patch instruction ("change Y to X in file Z"). State correction to spec stream:

Issue N implied X; implementation did Y; X correct. — or
Issue N specified Y; Y wrong; X′ now correct.

Replay then builds X directly, not bug + patch. Bugfix reveals spec-level decision → ADR + reference from issue.

绝不要给出补丁式指令（如“将文件Z中的Y改为X”）。应明确说明对规格说明流的修正：

工单N隐含要求为X；但实现为Y；正确应为X。 —— 或
工单N明确要求为Y；但Y是错误的；现在正确应为X′。

按工单流执行时将直接构建X，而非先构建带Bug的版本再打补丁。Bug修复需明确规格说明层面的决策 → 生成ADR并在工单中引用。

Reconciliation on completion

完成时的一致性核对

Ticket not finished until it reflects what was built. Before close: fold deviations, mid-session scope, decisions back into issue (or its ADR/glossary refs). Else replay builds first draft, not final state.

documenting-decisions

after-task step performs this.

只有当工单内容与实际构建结果一致时，才算完成。关闭工单前：需将偏差、中途调整的范围及新增决策整合到工单中（或其引用的ADR/术语表条目里）。否则按工单流执行时将构建出初稿，而非最终状态。

documenting-decisions

事后步骤负责完成此项工作。

Grilling gate

审核关卡

Tickets are load-bearing. No grilling session (

docs/glossary/grilling-session.md

) in context → stop, ask user: "No grilling session found — really skip?" Proceed only on explicit confirmation; note skip in parent issue/PR.

工单是核心载体。如果上下文未包含grilling session（

docs/glossary/grilling-session.md

）→ 需暂停操作，询问用户：“未找到grilling session——确定要跳过吗？”仅在用户明确确认后继续；并在父工单/PR中记录跳过操作。

Process

流程

1. Gather context

1. 收集上下文

Work from conversation context. User passes reference (spec path, issue number/URL) → fetch, read full body + comments.

基于对话上下文开展工作。若用户提供了参考链接（规格说明路径、工单号/URL）→ 获取并完整阅读内容及评论。

2. Explore codebase (optional)

2. 探索代码库（可选）

Understand current code state. Titles/descriptions use glossary vocabulary (

uvx disambiguate <term>

); respect ADRs in touched area.

Look for prefactoring opportunities. "Make the change easy, then make the easy change."

了解当前代码状态。工单标题/描述需使用术语表中的词汇（

uvx disambiguate <term>

）；需遵循受影响代码区域的ADRs。

寻找预重构的机会。遵循原则：“先让变更变得容易，再执行这个容易的变更。”

3. Draft vertical slices

3. 草拟垂直切片工单

Break work into tracer bullet tickets:

Each slice: narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT horizontal slice of one layer
Completed slice demoable/verifiable alone
Sized to one fresh context window
Prefactoring first

Each ticket declares blocking edges — tickets that must complete first. No blockers → start immediately.

Apply litmus test to every draft: drafting decisions (interfaces, naming, sequencing trade-offs) go into ticket body, ADR, or glossary term — mark per

documenting-decisions

Wide refactors: exception to vertical slicing. One mechanical change (rename column, retype shared symbol), blast radius spans codebase — single edit breaks thousands of call sites, no slice lands green. Sequence as expand–contract. Expand: new form beside old, nothing breaks. Migrate: call sites in batches sized by blast radius (per package/directory), each batch own ticket blocked by expand — CI stays green, old form still exists. Contract: delete old form once no caller remains, blocked by every batch. Batches can't stay green alone → keep sequence, share integration branch, all block final integrate-and-verify ticket — green promised only there.

将工作拆分为tracer bullet工单：

每个切片：覆盖所有层级（Schema、API、UI、测试）的窄而完整的路径——是垂直切片，而非单一层级的水平切片
完成后的切片可单独演示/验证
规模控制在单次上下文切换可处理的范围内
优先进行预重构

每个工单需声明阻塞依赖——即必须先完成的前置工单。若无阻塞依赖→可立即启动。

对每个草拟工单应用验证测试：草拟过程中的决策（接口、命名、顺序权衡）需记录到工单正文、ADR或术语表条目中——按

documenting-decisions

要求标记。

大范围重构：垂直切片的例外情况。 单一机械变更（如重命名列、修改共享符号类型），其影响范围覆盖整个代码库——单次修改会导致数千个调用点失效，无法通过垂直切片实现逐个绿色构建。需按扩展-收缩流程执行：扩展阶段：在旧实现旁新增新实现，确保现有功能不受影响。迁移阶段：按影响范围分批迁移调用点（按包/目录划分），每个批次对应一个工单，且依赖扩展阶段的工单——CI保持绿色，旧实现仍保留。收缩阶段：当无调用点依赖旧实现时删除旧实现，依赖所有迁移批次的工单。单独的迁移批次无法保持绿色构建→需严格遵循顺序，共享集成分支，所有批次工单都依赖最终的集成验证工单——仅在此工单中保证构建绿色。

4. Quiz user

4. 征询用户意见

Numbered list. Per ticket:

Title: short name
Blocked by: gating tickets, if any
What it delivers: end-to-end behaviour made to work

Ask:

Granularity right? (too coarse/fine)
Blocking edges correct — only genuine gates?
Merge or split any?
Any ticket failing litmus test — decision still only in conversation?

Iterate until approved.

以编号列表呈现每个工单的信息：

标题：简短名称
依赖阻塞：前置工单（如有）
交付内容：可正常运行的端到端功能

询问用户：

粒度是否合适？（过粗/过细）
阻塞依赖是否正确——是否仅包含真正的前置依赖？
是否需要合并或拆分某些工单？
是否有工单未通过验证测试——相关决策仍仅存在于对话中？

反复迭代直至用户批准。

5. Publish

5. 发布工单

One issue per ticket, dependency order (blockers first) → edges reference real issue numbers. Native blocking relation where tracker has one, else "Blocked by" section. Apply

ready-for-agent

label unless told otherwise — tickets agent-grabbable by construction.

Work the frontier: any ticket with all blockers done. Linear chain → top to bottom.

Do NOT close/modify parent issue.

Issue template:

markdown

undefined

每个工单对应一个问题，按依赖顺序发布（先发布前置工单）→ 依赖关系需引用真实的工单号。若追踪器支持原生阻塞关系则使用该功能，否则在工单中添加“依赖阻塞”章节。除非另有指示，否则添加

ready-for-agent

标签——此类工单可直接由Agent处理。

处理前沿工单：即所有前置依赖已完成的工单。线性链式工单→从上到下依次处理。

请勿关闭/修改父工单。

工单模板：

markdown

undefined

Parent

Reference to parent issue (omit if source wasn't an issue).

What to build

End-to-end behaviour, user's perspective — not layer-by-layer implementation.

Decisions

Every outcome-shaping decision, stated or referenced (ADR/glossary). Bugfix: spec-correction statement. Omit only if genuinely none.

Acceptance criteria

Criterion 1
Criterion 2

Criterion 1
Criterion 2

Blocked by

Reference per blocking ticket, or "None — can start immediately".


Ticket prose: as short as possible, caveman mode preferred (`caveman` skill) — precision and understandability must not suffer.

No file paths/code snippets — stale fast. Exception: prototype snippet encoding a decision more precisely than prose (state machine, reducer, schema, type shape) → inline, note prototype origin, trim to decision-rich parts.

Work frontier one ticket at a time, clearing context between tickets.

Reference per blocking ticket, or "None — can start immediately".


工单描述：尽可能简洁，优先采用caveman模式（`caveman`技能）——但不得牺牲准确性和可读性。

请勿包含文件路径/代码片段——此类内容极易过时。例外情况：若原型代码片段比文字更精准地表达决策（如状态机、Reducer、Schema、类型结构）→可嵌入工单，注明原型来源，并仅保留与决策相关的核心部分。

每次处理一个前沿工单，处理完成后清空上下文。