work-task

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Work Task

任务处理

Handle $ARGUMENTS. Be thorough, not ceremonial. Start from the source of truth, load extra skills only when they earn their keep, and verify before calling the task done.

<task>#$ARGUMENTS</task>

处理$ARGUMENTS。力求详尽，而非流于形式。从可信源出发，仅在确有必要时加载额外技能，完成任务前先进行验证。

<task>#$ARGUMENTS</task>

Core Rules

核心规则

Read the task source first.
Read local repo instructions and relevant files before editing.
Search for existing patterns before inventing new ones.
Prefer the best durable fix over the smallest local patch. If the root cause lives in an API or abstraction seam, change that seam even when it means a broader refactor or an intentional API change.
Prefer targeted tests and checks during iteration.
Keep the user updated at milestones.
Verify the actual result before claiming done.
Do not default to research swarms, review swarms, or browser proof.
For verified code-changing work, default to creating or updating the PR unless the user explicitly said not to.
Do not default to compounding.
Before calling a task blocked on a repo-wide gate, rule out local install corruption once when the failure smells wrong for the diff.

首先阅读任务源内容。
编辑前先阅读本地仓库说明和相关文件。
先查找现有模式，再创建新模式。
优先选择最佳的持久化修复方案，而非最小化的本地补丁。如果根本原因存在于API或抽象层，则修改该层级，即使这意味着更广泛的重构或有意的API变更。
迭代过程中优先使用针对性测试和检查。
在关键节点向用户更新进度。
宣称任务完成前先验证实际结果。
不要默认使用研究集群、评审集群或浏览器验证。
对于已验证的代码变更工作，默认创建或更新PR，除非用户明确说明不需要。
不要默认进行复合操作。
在宣称任务因仓库级网关受阻前，如果失败原因与代码变更不符，先排除本地安装损坏的可能性。

Intake

任务接收

Classify the input:
- Plain task text: the user prompt is the source of truth.
- File path or spec path: read it first.
- GitHub issue URL: fetch it with
```
gh issue view
```
  first.
- GitHub PR URL: fetch it with
```
gh pr view
```
  first.
- Bare GitHub issue like
```
#555
```
  : resolve it against the current
```
gh
```
  repo first, then fetch it with
```
gh issue view
```
  .
- Linear issue link/id: fetch it with the Linear integration first.
Read the full source-of-truth context before doing anything else.
If the task comes from a ticket or issue, also read the comments and attachments when available.
If the task comes from a tracker item and any attachment or linked media is a video or screen recording, you must have transcript output with
```
video-transcripts
```
before implementation.
- The canonical shared cache lives in the tracker next to the evidence it describes.
- Cache comment body should be XML only:

```xml
<video-transcripts>
<video-transcript
  source-key="https://tracker-hosted-video/<stable-path-without-query>"
>
[00:00] (...)
</video-transcript>
</video-transcripts>
```

```
source-key
```
must be the normalized stable identifier for the media. For signed tracker-hosted URLs like
```
uploads.linear.app
```
, strip the query string so rotating signatures do not bust the cache.
Do not add decorative metadata like
```
title
```
to cached
```
<video-transcript>
```
entries unless a later workflow truly needs it.
Group videos by source container before transcribing:
- one cache comment for issue or PR body videos
- GitHub: one dedicated top-level cache comment for each issue or PR comment that contains video(s)
- Linear: one cache reply for each comment that contains video(s)
Keep the cache body pure XML. Do not prepend markers, prose, or YAML.
Before running the helper, scan existing tracker comments and, when relevant, Linear replies. Match by source container first, then check whether the cached
```
<video-transcript ... source-key="...">
```
entries cover every current video URL for that container after the same normalization.
If the matching cache fully covers the current normalized video keys for that source container, reuse the cached XML block and do not re-transcribe.
If the cache is missing any current video, or that source container has new video evidence, transcribe only the missing videos and create or update the matching cache comment or reply.
Use the helper in $video-transcripts.
Run it once per relevant video attachment or URL.
For auth-gated tracker media like
```
uploads.linear.app
```
or private GitHub asset URLs, use the helper directly before declaring the video blocked. It can reuse local tracker auth when available.
Convert the video evidence into a normalized block in this exact shape before continuing:

xml

<video-transcripts>
<video-transcript source-key="...">
[00:00] (...)
</video-transcript>
</video-transcripts>

Use the generated or cached transcript output as part of the tracker context.
Do not hand-write, paraphrase, or skip video evidence when the skill can run.
If the helper still cannot fetch or transcribe the media after a real attempt, hard stop and report the exact blocker you hit.
Do not continue implementation without the transcript when a real video is present.

If there are multiple videos, preserve each as its own
```
<video-transcript ...>
```
block under one
```
<video-transcripts>
```
wrapper.
Classify the task shape before choosing a workflow:
- Testing or coverage work: triggered by coverage, regressions, test-suite phases, hotspots, package testing, or similar language.
- Program or batch work: triggered by multiple packages, phases, buckets, or ordered slices.
- Ordinary one-shot work: bug, feature, refactor, docs, review, or investigation that can be finished as a single slice.
Classify whether this is heavyweight framework or library work:
- Heavyweight work: architecture or public API redesign, breaking changes, major cross-package refactors, benchmarking, profiling strategy, performance comparison, scalability work, framework comparison, migration analysis, RFCs, proposals, or spec-first major changes.
- Non-heavyweight work: ordinary bugs, one-package features, docs-only edits, routine test work, small refactors, or normal issue execution even when non-trivial.
If the task is heavyweight work:
- load
```
major-task
```
  immediately
- treat
```
major-task
```
  as the source of truth for workflow and helper selection
- do not quietly inflate this task flow into a research swarm
If the task is not heavyweight work, classify task complexity before implementation:
- Non-trivial task: multi-step work, research-heavy work, phased execution, or anything likely to take more than a handful of tool calls.
- Trivial task: quick question, small edit, or other work that does not need persistent working memory.
If the task is non-trivial:

load
```
planning-with-files
```
before implementation
use persistent planning files or the repo's equivalent planning structure so progress survives context loss
follow local repo overrides for where planning files live
if the task touches published package code under
```
packages/
```
, record in the plan whether a changeset will be required before completion
if the task is registry-only work under
```
apps/www/src/registry/
```
, record in the plan whether
```
docs/components/changelog.mdx
```
must be updated instead of creating a package changeset

If the task is testing or coverage work:

restate it as test work, not generic feature work
load
```
testing
```
first and use that testing policy as the source of truth
choose the smallest honest seam before loading
```
tdd
```

If the task is program or batch work:

restate the ordered scope and hard constraints
do not treat the whole batch as one implementation unit
default to completing the first slice cleanly unless the user explicitly asks for a broader sweep

GitHub issue rules:

Resolve bare issue numbers like
```
#555
```
against the current repo with
```
gh repo view --json nameWithOwner -q '.nameWithOwner'
```
.

Fetch GitHub issues with:

bash

gh issue view <number-or-url> --comments --json number,title,body,comments,labels,state,url

Fetch GitHub PRs with
```
gh pr view ... --json
```
.
If the input is ambiguous and not clearly a GitHub issue token or URL, do not guess.

For any tracker source, restate for yourself:

source type
source id
exact title
task type: bug, feature, refactor, docs, review, investigation, testing, or batch work
expected outcome or acceptance criteria
caveats, blockers, or missing information from the tracker
likely files, routes, or packages affected
whether there is a real browser surface to verify
likely root-cause layer: call site, helper, abstraction seam, or public API

Read repo instructions and nearby implementation patterns before editing.
If the task changes code:

if already on a branch clearly dedicated to this exact task, continue there
treat a branch as "clearly dedicated" only when the branch name, tracker id, or existing PR obviously matches the current task
do not reuse an unrelated non-
```
main
```
branch just because you are already on it
if the current branch is not clearly dedicated to this task, check out
```
main
```
, pull the latest
```
main
```
, then create a fresh repo-convention branch before editing
if the task has a tracker id, prefer a branch name that includes it:
- GitHub issue:
```
codex/555-short-slug
```
- Linear issue:
```
codex/LIN-123-short-slug
```
in this repo, otherwise prefer
```
codex/<slug>
```
run install or setup only when the repo or task actually needs it

If the task does not change code, skip branch and setup noise.
If anything important is still ambiguous after the source-of-truth pass and nearby code reading, ask the user the smallest useful clarifying question.

对输入进行分类：
- 纯任务文本：用户提示即为可信源。
- 文件路径或规范路径：先读取该路径内容。
- GitHub issue URL：先使用
```
gh issue view
```
  获取内容。
- GitHub PR URL：先使用
```
gh pr view
```
  获取内容。
- 纯GitHub issue编号如
```
#555
```
  ：先在当前
```
gh
```
  仓库中解析，再使用
```
gh issue view
```
  获取内容。
- Linear issue链接/ID：先通过Linear集成获取内容。
在进行任何操作前，先完整阅读可信源上下文。
如果任务来自工单或issue，同时阅读可用的评论和附件。
如果任务来自跟踪项，且任何附件或关联媒体为视频或屏幕录制，在实现前必须使用
```
video-transcripts
```
生成转录文本输出。
- 标准共享缓存位于跟踪器中，与对应的证据相邻。
- 缓存评论内容必须仅为XML格式：

```xml
<video-transcripts>
<video-transcript
  source-key="https://tracker-hosted-video/<stable-path-without-query>"
>
[00:00] (...)
</video-transcript>
</video-transcripts>
```

```
source-key
```
必须是媒体的标准化稳定标识符。对于像
```
uploads.linear.app
```
这样的签名跟踪器托管URL，移除查询字符串，避免轮换签名破坏缓存。
除非后续工作流确实需要，否则不要为缓存的
```
<video-transcript>
```
条目添加
```
title
```
等装饰性元数据。
转录前按源容器对视频进行分组：
- issue或PR正文中的视频使用一个缓存评论
- GitHub：每个包含视频的issue或PR评论使用一个独立的顶级缓存评论
- Linear：每个包含视频的评论使用一个缓存回复
保持缓存内容为纯XML格式。不要添加标记、散文或YAML前缀。
运行助手前，扫描现有跟踪器评论和相关Linear回复。先按源容器匹配，再检查缓存的
```
<video-transcript ... source-key="...">
```
条目是否覆盖该容器中所有经过相同标准化处理的当前视频URL。
如果匹配的缓存完全覆盖该源容器当前的标准化视频键，则复用缓存的XML块，无需重新转录。
如果缓存缺少任何当前视频，或该源容器有新的视频证据，则仅转录缺失的视频，并创建或更新匹配的缓存评论或回复。
使用$video-transcripts中的助手。
每个相关视频附件或URL运行一次。
对于
```
uploads.linear.app
```
或私有GitHub资产URL等需要授权的跟踪器媒体，在宣称视频受阻前直接使用助手。它可以在可用时复用本地跟踪器授权。
在继续操作前，将视频证据转换为以下精确格式的标准化块：

xml

<video-transcripts>
<video-transcript source-key="...">
[00:00] (...)
</video-transcript>
</video-transcripts>

将生成或缓存的转录文本输出作为跟踪器上下文的一部分。
当技能可运行时，不要手写、转述或跳过视频证据。
如果助手经过实际尝试仍无法获取或转录媒体，则立即停止并报告遇到的具体障碍。
当存在真实视频时，不要在没有转录文本的情况下继续实现。

如果有多个视频，将每个视频保留为独立的
```
<video-transcript ...>
```
块，置于一个
```
<video-transcripts>
```
包装器下。
在选择工作流前对任务类型进行分类：
- 测试或覆盖率工作：由覆盖率、回归、测试套件阶段、热点、包测试或类似术语触发。
- 程序化或批量工作：由多个包、阶段、分组或有序片段触发。
- 普通一次性工作：可作为单个片段完成的bug修复、功能开发、重构、文档编写、评审或调查。
分类是否为重量级框架或库工作：
- 重量级工作：架构或公共API重新设计、破坏性变更、跨包重大重构、基准测试、性能分析策略、性能对比、可扩展性工作、框架对比、迁移分析、RFC、提案或规范优先的重大变更。
- 非重量级工作：普通bug修复、单包功能开发、仅文档编辑、常规测试工作、小型重构或正常issue执行，即使任务并非微不足道。
如果任务是重量级工作：
- 立即加载
```
major-task
```
- 将
```
major-task
```
  作为工作流和助手选择的可信源
- 不要悄悄将此任务流程扩展为研究集群
如果任务不是重量级工作，在实现前对任务复杂度进行分类：
- 非琐碎任务：多步骤工作、研究密集型工作、分阶段执行或任何可能需要多次工具调用的工作。
- 琐碎任务：快速问题、小型编辑或其他不需要持久工作记忆的工作。
如果任务是非琐碎任务：
- 实现前加载
```
planning-with-files
```
- 使用持久化规划文件或仓库的等效规划结构，确保进度不会因上下文丢失而中断
- 遵循本地仓库关于规划文件存放位置的覆盖规则
- 如果任务涉及
```
packages/
```
  下的已发布包代码，在规划中记录完成前是否需要changeset
- 如果任务是
```
apps/www/src/registry/
```
  下的仅注册表工作，在规划中记录是否需要更新
```
docs/components/changelog.mdx
```
  而非创建包changeset
如果任务是测试或覆盖率工作：
- 将其重述为测试工作，而非通用功能工作
- 首先加载
```
testing
```
  并将该测试策略作为可信源
- 在加载
```
tdd
```
  前选择最小的合理层级
如果任务是程序化或批量工作：
- 重述有序范围和硬约束
- 不要将整个批量视为一个实现单元
- 默认先完整完成第一个片段，除非用户明确要求更广泛的处理
GitHub issue规则：
- 使用
```
gh repo view --json nameWithOwner -q '.nameWithOwner'
```
  在当前仓库中解析纯issue编号如
```
#555
```
  。
- 使用以下命令获取GitHub issue：
  bash
```
gh issue view <number-or-url> --comments --json number,title,body,comments,labels,state,url
```
- 使用
```
gh pr view ... --json
```
  获取GitHub PR。
- 如果输入不明确且并非明显的GitHub issue标记或URL，不要猜测。
对于任何跟踪器源，自行明确：

源类型
源ID
确切标题
任务类型：bug修复、功能开发、重构、文档编写、评审、调查、测试或批量工作
预期结果或验收标准
跟踪器中的注意事项、障碍或缺失信息
可能受影响的文件、路由或包
是否存在需要验证的真实浏览器界面
可能的根本原因层级：调用站点、助手、抽象层或公共API

编辑前阅读仓库说明和附近的实现模式。
如果任务涉及代码变更：

如果已在专门用于此任务的分支上，则继续在该分支工作
只有当分支名称、跟踪器ID或现有PR明显匹配当前任务时，才将该分支视为“明确专用”
不要仅仅因为已在某个分支上就复用无关的非
```
main
```
分支
如果当前分支并非明确专用于此任务，则切换到
```
main
```
分支，拉取最新的
```
main
```
代码，然后创建符合仓库规范的新分支再进行编辑
如果任务有跟踪器ID，优先使用包含该ID的分支名称：
- GitHub issue：
```
codex/555-short-slug
```
- Linear issue：
```
codex/LIN-123-short-slug
```
在本仓库中，否则优先使用
```
codex/<slug>
```
格式
仅当仓库或任务实际需要时才运行安装或设置

如果任务不涉及代码变更，跳过分支和设置相关操作。
如果在可信源检查和附近代码阅读后仍有重要信息不明确，向用户提出最有用的简短澄清问题。

Tracked Task Rules

跟踪任务规则

Apply this section only when the task source is a tracker item.

仅当任务源为跟踪项时应用本节内容。

GitHub

Treat the GitHub issue as the source of truth.
Use
```
gh
```
for fetch and sync-back.
If useful, rename the thread to
```
<issue-number> <issue-title>
```
.
If the task is code-changing, prefer a branch name that includes the issue number.
If the task changed code and reached a verified meaningful outcome, create or update the PR before any issue comment unless blocked or the user said not to.
If the task reaches a meaningful outcome and came from the issue, post a concise issue comment after the PR exists unless blocked or the user said not to.

将GitHub issue视为可信源。
使用
```
gh
```
进行获取和同步回传。
如果有用，将线程重命名为
```
<issue-number> <issue-title>
```
。
如果任务涉及代码变更，优先使用包含issue编号的分支名称。
如果任务涉及代码变更并达到已验证的有意义结果，在发布任何issue评论前创建或更新PR，除非受阻或用户明确说明不需要。
如果任务达到有意义结果且来自issue，在PR存在后发布简洁的issue评论，除非受阻或用户明确说明不需要。

Linear

Keep the same fetch-first behavior as the dedicated Linear workflow.
Read the issue, comments, and attachments before implementation.
Keep comment-back QA-focused.
Do not force browser proof unless the task actually has a browser surface.

保持与专用Linear工作流相同的先获取行为。
实现前阅读issue、评论和附件。
同步回传的评论以QA为重点。
除非任务确实有浏览器界面，否则不要强制进行浏览器验证。

Tracked Task Non-Rules

跟踪任务非规则

Do not require PR creation for tracker tasks that did not change code, ended blocked, or were purely investigative.
Do not require browser screenshots for every tracked task.
Do not require tracker comments for investigations that ended blocked or inconclusive unless sync-back is useful.

对于未涉及代码变更、受阻或纯调查性的跟踪任务，不要求创建PR。
不要求每个跟踪任务都提供浏览器截图。
对于受阻或无结论的调查，除非同步回传有用，否则不要求发布跟踪器评论。

Load Skills Only When Justified

仅在合理时加载技能

```
planning-with-files
```
Use for any non-trivial task that needs persistent working memory, phased execution, or likely more than a handful of tool calls. Follow repo-specific overrides for where planning artifacts should live.
```
major-task
```
Use for architecture or public API redesign, benchmarking or scalability work, framework comparison or migration analysis, major cross-package refactors, or RFC and proposal work. When it triggers during intake, it becomes the source of truth instead of this file.
```
testing
```
Use when the task is primarily about tests, coverage, regression gaps, or phase-based suite work. Load it before
```
tdd
```
for testing programs.
```
tdd
```
Use for bugs and for feature work where behavior-level automated coverage is sane. For testing programs, load it only after choosing a concrete slice that should be done test-first. Skip for trivial docs, mechanical refactors, or painful UI-only plumbing.
```
learnings-researcher
```
Use for non-trivial work in a domain with documented solutions or when the task smells like a repeated issue. Do not load it for tiny isolated edits.
```
debug
```
Use when the failure mode is still fuzzy after the first repro pass or first failing test.
```
video-transcripts
```
Use when a tracker issue, PR, comment thread, or attachment set includes any video or screen recording that should become structured transcript evidence before implementation.
```
ce:brainstorm
```
Use when requirements are still ambiguous after reading the source of truth and nearby code.
```
framework-docs-researcher
```
Use when touching unfamiliar, version-sensitive, or unstable third-party APIs after checking local clones and docs per AGENTS.
```
dev-browser
```
Use only when there is a real browser surface to verify. Require real browser proof only for browser or UI tasks.
```
agent-browser-issue
```
Use when browser automation is blocked by a likely reusable tool-side issue that should be split into its own GitHub follow-up.
```
changeset
```
Use when verified work changes a published package under
```
packages/
```
and the repo expects release notes before completion. Do not create a package changeset for registry-only work under
```
apps/www/src/registry/
```
; update
```
docs/components/changelog.mdx
```
instead.
```
git-commit-push-pr
```
Use when verified work changed code and should ship as a PR. Create or update the PR before any tracker comment. The PR description should be the exact current final handoff, not a rewritten summary. If the task changes again in a later iteration, update the PR description to match the latest handoff.
```
ce-compound
```
Use only after verified, non-trivial work that produced reusable knowledge. Never load it at the start.

ce-review

correctness-reviewer

maintainability-reviewer

project-standards-reviewer

code-simplicity-reviewer

Use only for risky, large, user-facing, or architecture-sensitive changes.

```
agent-native-reviewer
```
Use only when the change touches
```
.agents/**
```
,
```
.claude/**
```
, AI/tooling surfaces, commands, or user actions that an agent should also be able to perform.

```
planning-with-files
```
用于任何需要持久工作记忆、分阶段执行或可能需要多次工具调用的非琐碎任务。遵循仓库特定的规划工件存放位置覆盖规则。
```
major-task
```
用于架构或公共API重新设计、基准测试或可扩展性工作、框架对比或迁移分析、跨包重大重构，或RFC和提案工作。当在任务接收阶段触发时，它将替代本文件成为可信源。
```
testing
```
当任务主要涉及测试、覆盖率、回归缺口或分阶段套件工作时使用。对于测试程序，在加载
```
tdd
```
前先加载它。
```
tdd
```
用于bug修复和行为级自动化覆盖率合理的功能开发工作。对于测试程序，仅在选择了应先进行测试的具体片段后加载。琐碎的文档编辑、机械重构或繁琐的仅UI plumbing工作跳过此技能。
```
learnings-researcher
```
用于有文档化解决方案的领域中的非琐碎工作，或任务看起来像是重复出现的问题时使用。不要为微小的孤立编辑加载此技能。
```
debug
```
当首次重现或首次失败测试后故障模式仍不明确时使用。
```
video-transcripts
```
当跟踪器issue、PR、评论线程或附件集包含任何视频或屏幕录制，且需要在实现前转换为结构化转录证据时使用。
```
ce:brainstorm
```
当阅读可信源和附近代码后需求仍不明确时使用。
```
framework-docs-researcher
```
当根据AGENTS检查本地克隆和文档后，仍需接触不熟悉、版本敏感或不稳定的第三方API时使用。
```
dev-browser
```
仅当存在需要验证的真实浏览器界面时使用。仅对浏览器或UI任务要求真实浏览器验证。
```
agent-browser-issue
```
当浏览器自动化被可能可复用的工具端问题阻塞，且该问题应拆分为独立的GitHub后续issue时使用。
```
changeset
```
当已验证的工作变更了
```
packages/
```
下的已发布包，且仓库要求完成前提供发布说明时使用。不要为
```
apps/www/src/registry/
```
下的仅注册表工作创建包changeset；应更新
```
docs/components/changelog.mdx
```
。
```
git-commit-push-pr
```
当已验证的工作变更了代码且应作为PR发布时使用。在发布任何跟踪器评论前创建或更新PR。 PR描述应与当前最终的交接内容完全一致，而非改写的摘要。如果后续迭代中任务发生变更，更新PR描述以匹配最新的交接内容。
```
ce-compound
```
仅在已验证的、产生可复用知识的非琐碎工作完成后使用。绝不在开始时加载。

ce-review

correctness-reviewer

maintainability-reviewer

project-standards-reviewer

code-simplicity-reviewer

仅用于高风险、大型、面向用户或架构敏感的变更。

```
agent-native-reviewer
```
仅当变更涉及
```
.agents/**
```
,
```
.claude/**
```
, AI/工具界面、命令或Agent也应能执行的用户操作时使用。

Execution Path

执行路径

Bug

Bug修复

Reproduce first if possible.
If behavior-level coverage is sane, turn the repro into the smallest useful automated test and watch it fail for the right reason.
Find the real ownership boundary of the bug. Prefer fixing the abstraction, contract, or API that caused it instead of patching each caller around it.
If the best fix requires an API change, make it unless the task source or repo constraints explicitly rule that out. Do not preserve a bad API just to keep the diff small.
If you intentionally choose a narrower fix, state why the broader architecture fix was not worth shipping now.
Re-run targeted checks.
Re-run the browser flow only if the bug lives on a browser surface.

尽可能先重现问题。
如果行为级覆盖率合理，将重现步骤转换为最小的有用自动化测试，并确认测试因正确原因失败。
找到bug的实际归属边界。优先修复导致bug的抽象层、契约或API，而非修补每个调用方。
如果最佳修复需要API变更，则进行变更，除非任务源或仓库约束明确禁止。不要为了缩小代码变更范围而保留不良API。
如果有意选择更窄的修复方案，说明为何更广泛的架构修复目前不值得发布。
重新运行针对性检查。
仅当bug存在于浏览器界面时，重新运行浏览器流程。

Feature

功能开发

Reduce the task to the smallest slice that fully satisfies the acceptance criteria.
Add behavior coverage when sane.
Prefer the cleanest long-term design that fits the slice, not the quickest bolt-on.
If existing patterns are the reason the design is weak, improve the pattern or API instead of copying it blindly.
Verify the user-facing outcome.

将任务精简为完全满足验收标准的最小片段。
行为级覆盖率合理时添加该覆盖。
优先选择适合该片段的最简洁长期设计，而非最快的临时方案。
如果现有模式导致设计薄弱，改进模式或API，而非盲目复制。
验证面向用户的结果。

Testing Or Coverage Work

测试或覆盖率工作

Use the testing policy as the rulebook before choosing seams or commands.
Identify the smallest honest seam for the first hotspot or ordered slice.
Add or deepen the narrowest useful tests instead of spraying smoke coverage.
Verify with targeted test commands first.
Use broader suite checks only when repo rules or change scope justify them.

在选择层级或命令前，将测试策略作为规则手册。
为第一个热点或有序片段确定最小的合理层级。
添加或深化最窄的有用测试，而非广泛添加烟雾测试。
首先使用针对性测试命令进行验证。
仅当仓库规则或变更范围需要时，才使用更广泛的套件检查。

Program Or Batch Work

程序化或批量工作

Respect the explicit order from the task source.
Do not fan out across every listed slice immediately.
Define what "done for this slice" means before implementation.
Complete one slice at a time unless the user explicitly asks for broader execution.

遵循任务源中的明确顺序。
不要立即展开到所有列出的片段。
在实现前定义“此片段完成”的标准。
一次完成一个片段，除非用户明确要求更广泛的执行。

Refactor Or Chore

重构或杂务

Preserve behavior.
Do not do fake TDD theater.
If the task exposes a bad API or abstraction, fix that seam instead of polishing around it.
Run the narrowest regression checks plus the relevant build, typecheck, or lint path for the touched area.

保留原有行为。
不要进行虚假的TDD形式化操作。
如果任务暴露了不良API或抽象层，修复该层级，而非仅做表面优化。
运行最窄的回归检查，以及受影响区域的相关构建、类型检查或lint路径。

Docs Or Content

文档或内容

Skip engineering ceremony.
Verify links, examples, formatting, and rendered output as appropriate.

跳过工程形式化流程。
根据情况验证链接、示例、格式和渲染输出。

Review Or Investigation

评审或调查

Read the relevant diff, files, and surrounding context first.
For review tasks, report findings first, ordered by severity, with concrete file references.
For investigation tasks, identify the failure mode, probable cause, and next action before changing code.
Only implement changes if the user actually asked for them.

首先阅读相关代码变更、文件和周围上下文。
对于评审任务，首先按严重性排序报告发现，并附带具体文件引用。
对于调查任务，在变更代码前确定故障模式、可能原因和下一步行动。
仅当用户明确要求时才实施变更。

Verification

验证

Keep verification mandatory but proportional.

Run targeted tests for changed behavior.
Run package or app build and typecheck when relevant to the touched area.
Run lint when code changed and the repo expects it.
Run browser verification only for browser or UI tasks.
Run broader repo-wide gates only when repo instructions require them or the change scope justifies them.
If a failing
```
pnpm test
```
,
```
bun test
```
, or
```
pnpm check
```
shows local-corruption signals unrelated to the current diff, run
```
pnpm run reinstall
```
once and rerun the exact failing command before declaring the task blocked. Treat these as local-corruption signals:
- ```
Invalid hook call
```
- ```
resolveDispatcher()
```
  / null dispatcher crashes
- package-local
```
node_modules/react
```
  or
```
node_modules/react-dom
```
  paths under
```
packages/*
```
- mixed
```
.bun
```
  and
```
.pnpm
```
  React paths in the same failing stack
- missing-module or package-resolution garbage that does not match the diff
If the repo has a standard final gate, run it last.
If verified work changes a published package under
```
packages/
```
, ensure the required changeset exists before PR or final handoff.
If the work is registry-only under
```
apps/www/src/registry/
```
, update
```
docs/components/changelog.mdx
```
instead of creating a package changeset.
If verified work changed code, create or update the PR before tracker sync-back unless the user explicitly said not to.
If the task came from a tracked issue and the task reached a meaningful outcome, sync back unless the user said not to.
If UI changed, capture proof from the real browser surface.
Do not hardcode PR creation, screenshots, or tracker comments for every task.

验证是强制性的，但需与变更范围相匹配。

对变更的行为运行针对性测试。
当涉及受影响区域时，运行包或应用构建和类型检查。
当代码变更且仓库要求时，运行lint。
仅对浏览器或UI任务运行浏览器验证。
仅当仓库说明要求或变更范围需要时，才运行更广泛的仓库级网关检查。
如果
```
pnpm test
```
、
```
bun test
```
或
```
pnpm check
```
失败，且显示与当前代码变更无关的本地损坏信号，运行
```
pnpm run reinstall
```
一次，然后重新运行失败的命令，再宣称任务受阻。以下情况视为本地损坏信号：
- ```
Invalid hook call
```
- ```
resolveDispatcher()
```
  / null dispatcher崩溃
- ```
packages/*
```
  下的包本地
```
node_modules/react
```
  或
```
node_modules/react-dom
```
  路径
- 同一失败堆栈中混合了
```
.bun
```
  和
```
.pnpm
```
  React路径
- 与代码变更不符的缺失模块或包解析错误
如果仓库有标准最终网关，最后运行它。
如果已验证的工作变更了
```
packages/
```
下的已发布包，确保PR或最终交接前存在所需的changeset。
如果工作是
```
apps/www/src/registry/
```
下的仅注册表工作，更新
```
docs/components/changelog.mdx
```
而非创建包changeset。
如果已验证的工作变更了代码，在跟踪器同步回传前创建或更新PR，除非用户明确说明不需要。
如果任务来自跟踪issue且达到有意义结果，进行同步回传，除非用户明确说明不需要。
如果UI发生变更，从真实浏览器界面获取验证证据。
不要为每个任务硬编码PR创建、截图或跟踪器评论要求。

Final Handoff

最终交接

Every final response must include:

follow repo writing style here too:
- be extremely concise
- sacrifice grammar for concision
- no filler, no narration, no polite padding
leading flat metadata lines in this exact order:
- ```
🔀 PR ...
```
- ```
🐛 Fixes ...
```
  for bug issues, otherwise use a generic issue line
- ```
🟢 95-100% confidence
```

then the flow table in this exact format:

```
| Phase | 🧪 Tests | 🌐 Browser |
```
```
| --- | --- | --- |
```

use these flow rows, in this order:
- ```
Reproduced
```
- ```
Verified
```
use markdown links for
```
PR
```
and
```
Issue
```
when they exist
for non-bug tracked work, do not fake a bug label; use a neutral issue line instead
keep the issue line stable; do not add issue comment links there
use these exact status values in the flow table:
- ```
✅
```
- ```
❌
```
- ```
➖ N/A
```
- prefer specific browser caveat text over vague
```
⚠️ Partial
```
  , for example
```
⚠️ Could not automate dropdown
```
in the
```
🧪 Tests
```
column:
- use
```
🔴
```
  in
```
Reproduced
```
  when there was a real failing test first
- use
```
🟢
```
  in
```
Verified
```
  when that test passed after the fix
- use
```
✅
```
  when test evidence exists but did not follow a real red-green loop
use
```
➖ N/A
```
for rows or cells that do not apply; do not invent a PR, issue, or comment
flow-table test cells mean test-based evidence, whether that came from TDD, a regression test, or another targeted test path
if manual non-browser reproduction or verification happened, explain it in the prose below the metadata lines + flow table rather than adding extra rows

Confidence

must stay

100%

or lower and use this line format:

```
🟢 95-100% confidence
```
```
🟡 80-94% confidence
```
```
🔴 below 80% confidence
```

after the metadata lines + flow table, use these short sections in this order:
- ```
**🌐 Browser Check**
```
  , only when browser verification applies
- ```
**✅ Outcome**
```
- ```
**⚠️ Caveat**
```
- ```
**🏗️ Design**
```
- ```
**🧪 Verified**
```
keep those sections flat, concise, and easy to scan
keep prose brutally short; prefer bullets over paragraphs here
if browser verification applies,
```
**🌐 Browser Check**
```
must include the exact human steps to verify the fix in the browser
```
**🏗️ Design**
```
is mandatory for any non-trivial code-changing task and must include:
- ```
Chosen seam: ...
```
- ```
Why not quick patch: ...
```
- ```
Why not broader change: ...
```
  only if a broader API or abstraction change was a real option

每个最终回复必须包含：

遵循仓库写作风格：
- 极其简洁
- 为简洁性可牺牲语法
- 无冗余内容、无叙述、无客套话
按以下精确顺序排列的顶级元数据行：
- ```
🔀 PR ...
```
- bug issue使用
```
🐛 Fixes ...
```
  ，否则使用通用issue行
- ```
🟢 95-100% confidence
```

然后是以下精确格式的流程表：

```
| Phase | 🧪 Tests | 🌐 Browser |
```
```
| --- | --- | --- |
```

使用以下流程行，按此顺序：
- ```
Reproduced
```
- ```
Verified
```
当PR和Issue存在时使用markdown链接
对于非bug跟踪工作，不要伪造bug标签；使用中性issue行
保持issue行稳定；不要在此添加issue评论链接
在流程表中使用以下精确状态值：
- ```
✅
```
- ```
❌
```
- ```
➖ N/A
```
- 优先使用具体的浏览器注意事项文本，而非模糊的
```
⚠️ Partial
```
  ，例如
```
⚠️ Could not automate dropdown
```
在
```
🧪 Tests
```
列中：
- 当初始存在真实失败测试时，在
```
Reproduced
```
  行使用
```
🔴
```
- 修复后测试通过时，在
```
Verified
```
  行使用
```
🟢
```
- 当存在测试证据但未遵循真实的红-green循环时，使用
```
✅
```
对不适用的行或单元格使用
```
➖ N/A
```
；不要虚构PR、issue或评论
流程表中的测试单元格表示基于测试的证据，无论来自TDD、回归测试还是其他针对性测试路径
如果进行了手动非浏览器重现或验证，在元数据行+流程表下方的散文中解释，而非添加额外行

Confidence

必须为

100%

或更低，并使用以下格式：

```
🟢 95-100% confidence
```
```
🟡 80-94% confidence
```
```
🔴 below 80% confidence
```

在元数据行+流程表之后，按以下顺序使用这些简短章节：
- ```
**🌐 Browser Check**
```
  ，仅当浏览器验证适用时
- ```
**✅ Outcome**
```
- ```
**⚠️ Caveat**
```
- ```
**🏗️ Design**
```
- ```
**🧪 Verified**
```
保持这些章节简洁、扁平化且易于扫描
保持散文极为简短；优先使用项目符号而非段落
如果浏览器验证适用，
```
**🌐 Browser Check**
```
必须包含在浏览器中验证修复的确切人工步骤
```
**🏗️ Design**
```
对于任何非琐碎代码变更任务是强制性的，必须包含：
- ```
Chosen seam: ...
```
- ```
Why not quick patch: ...
```
- ```
Why not broader change: ...
```
  （仅当更广泛的API或抽象层变更是真实选项时）

UI Or Browser Tasks

UI或浏览器任务

Include at least one real browser proof screenshot in the final response.
The screenshot must come from
```
dev-browser
```
or the real browser workflow used for verification.
When
```
**🌐 Browser Check**
```
is present, put the screenshot immediately after that section.
Otherwise, put the screenshot immediately after the metadata lines + flow table, before the completion summary.
If no real browser proof exists, the task is not done unless the user explicitly waived it.
If
```
dev-browser
```
is blocked on a likely reusable tool-side issue and the product task is still otherwise fixable, load
```
agent-browser-issue
```
.
If that follow-up issue is opened, mention it in the caveat or handoff.
```
**🌐 Browser Check**
```
must be a flat bullet list:
- keep it short and concrete
- prefer the exact local URL as a markdown link when one exists, for example http://localhost:3000/...
- use the real page, route, and interaction names
- focus on how to prove the fix, not on implementation detail

最终回复中至少包含一张真实浏览器验证截图。
截图必须来自
```
dev-browser
```
或用于验证的真实浏览器工作流。
当存在
```
**🌐 Browser Check**
```
时，将截图直接置于该章节之后。
否则，将截图直接置于元数据行+流程表之后、完成摘要之前。
如果没有真实浏览器验证证据，除非用户明确豁免，否则任务未完成。
如果
```
dev-browser
```
被可能可复用的工具端问题阻塞，但产品任务仍可修复，加载
```
agent-browser-issue
```
。
如果后续issue已创建，在注意事项或交接中提及。
```
**🌐 Browser Check**
```
必须为扁平化项目符号列表：
- 保持简短且具体
- 当存在本地URL时优先使用markdown链接，例如http://localhost:3000/...
- 使用真实页面、路由和交互名称
- 重点说明如何验证修复，而非实现细节

Non-UI Tasks

非UI任务

No screenshot is required.
Omit
```
**🌐 Browser Check**
```
when there is no browser surface.
Keep the final response concise and evidence-based.

无需截图。
当没有浏览器界面时省略
```
**🌐 Browser Check**
```
。
保持最终回复简洁且基于证据。

Testing Or Batch Work

测试或批量工作

State which slice, bucket, or hotspot was completed.
State what verification ran for that completed slice.
State what remains queued by design.
State any intentional deferral in generic terms only.

说明已完成的片段、分组或热点。
说明对已完成片段运行的验证操作。
说明按设计仍在队列中的内容。
仅以通用术语说明任何有意推迟的内容。

Review Or Investigation Tasks

评审或调查任务

Lead with findings or conclusion, not process notes.

以发现或结论开头，而非流程说明。

Post Back To Tracker

同步回传至跟踪器

Apply this section only when the task came from a tracker item and reached a meaningful outcome.

仅当任务来自跟踪项且达到有意义结果时应用本节内容。

Pull Request

拉取请求（PR）

When a PR exists, the PR description must match the exact current final handoff from chat:
- same flow table
- same metadata lines, except omit the leading
```
🔀 PR ...
```
  line because the PR page already identifies itself
- same screenshot when applicable
- same
```
**✅ Outcome**
```
  ,
```
**🏗️ Design**
```
  ,
```
**🧪 Verified**
```
  ,
```
**⚠️ Caveat**
```
  , and
```
**🌐 Browser Check**
```
  sections when applicable
- same caveats
- same human browser verification steps when applicable
PR description follows the same writing style:
- extremely concise
- grammar can be sacrificed for concision
- no fluffy framing
Do not publish a PR description with a dead local proof path.
If screenshot proof is local, upload it first and only then write or update the final PR body with the hosted GitHub URL.
For a brand-new PR, if the hosted proof URL is not ready yet:
- create the PR with no proof image
- upload the image immediately
- replace the placeholder with the real hosted proof before handoff
If the PR description includes a local image path for proof, do not leave it that way on GitHub.
Use
```
dev-browser --connect http://127.0.0.1:9222
```
to upload the image through the PR comment file input as a staging area, then replace the local proof path in the PR body with the hosted GitHub attachment URL.
Use the PR comment textarea only as staging:
- upload image
- read generated markdown or URL from the textarea
- clear the textarea
- do not submit the staging comment
Do not spend time reloading the PR page just to verify hosted image rendering unless the user explicitly asks.
Do not compress, adapt, or rewrite the handoff for the PR description.
If a later iteration changes the fix, evidence, certainty, caveats, or verification, update the PR description again so it stays in sync.
Update the PR description before writing the issue comment.

当PR存在时，PR描述必须与聊天中的当前最终交接内容完全一致：
- 相同的流程表
- 相同的元数据行，除了省略开头的
```
🔀 PR ...
```
  行，因为PR页面已自标识
- 适用时使用相同的截图
- 适用时使用相同的
```
**✅ Outcome**
```
  、
```
**🏗️ Design**
```
  、
```
**🧪 Verified**
```
  、
```
**⚠️ Caveat**
```
  和
```
**🌐 Browser Check**
```
  章节
- 相同的注意事项
- 适用时使用相同的人工浏览器验证步骤
PR描述遵循相同的写作风格：
- 极其简洁
- 为简洁性可牺牲语法
- 无冗余框架性内容
不要发布包含无效本地验证路径的PR描述。
如果截图验证是本地的，先上传截图，然后再使用托管的GitHub URL编写或更新最终PR正文。
对于全新PR，如果托管验证URL尚未准备好：
- 创建无验证图片的PR
- 立即上传图片
- 在交接前将占位符替换为真实的托管验证URL
如果PR描述包含本地图片路径作为验证证据，不要在GitHub上保留该状态。
使用
```
dev-browser --connect http://127.0.0.1:9222
```
通过PR评论文件输入上传图片作为暂存区，然后将PR正文中的本地验证路径替换为托管的GitHub附件URL。
仅将PR评论文本框用作暂存区：
- 上传图片
- 从文本框中读取生成的markdown或URL
- 清空文本框
- 不要提交暂存评论
除非用户明确要求，否则不要花费时间重新加载PR页面以验证托管图片的渲染。
不要为PR描述压缩、调整或改写交接内容。
如果后续迭代变更了修复、证据、确定性、注意事项或验证内容，再次更新PR描述以保持同步。
在编写issue评论前更新PR描述。

GitHub Issue

Use:

bash

gh issue comment <number-or-url> --body-file -

Keep it user-facing and e2e-centric.
Keep it extremely concise. Grammar can be sacrificed for concision.
Start with a single plain line in this shape:
- ```
✅ Fixed in #<pr-number>.
```
Follow with a flat bullet list only:
- manual verification steps for the real user flow
- optional final QA or caveat bullet when useful
Do not mention:
- Codex
- file names
- tests, typecheck, or lint
- screenshot paths
- branch names
- commit, push, or staging mechanics
Do not write the issue comment before the PR exists.
If writing the comment after code-changing work, use the PR number form
```
#123
```
, not the full URL.

Example:

✅ Fixed in #123.

- Open the affected page.
- Follow the real user flow that triggered the bug.
- Confirm the fixed behavior in the browser.
- Manual QA is still useful if browser verification was partial.

使用：

bash

gh issue comment <number-or-url> --body-file -

保持面向用户且以端到端为中心。
保持极其简洁。为简洁性可牺牲语法。
以以下格式的单行纯文本开头：
- ```
✅ Fixed in #<pr-number>.
```
仅跟随扁平化项目符号列表：
- 真实用户流程的手动验证步骤
- 有用时可选的最终QA或注意事项项目符号
不要提及：
- Codex
- 文件名
- 测试、类型检查或lint
- 截图路径
- 分支名称
- 提交、推送或暂存机制
不要在PR存在前编写issue评论。
如果在代码变更工作后编写评论，使用PR编号格式
```
#123
```
，而非完整URL。

示例：

✅ Fixed in #123.

- 打开受影响的页面。
- 触发bug的真实用户流程。
- 在浏览器中确认修复后的行为。
- 如果浏览器验证不完整，手动QA仍有用。

Linear

Keep proof local. Do not upload screenshots or other files to Linear.
Post a concise issue comment using the Linear integration.
Match the ticket style and write for QA, not developers.
Keep the same terse style:
- extremely concise
- grammar can be sacrificed for concision
- avoid file names, tests, typecheck, lint, branch names, PR mechanics, and screenshot paths

保持验证证据本地存储。不要将截图或其他文件上传至Linear。
使用Linear集成发布简洁的issue评论。
匹配工单风格，为QA而非开发者编写。
保持相同的简洁风格：
- 极其简洁
- 为简洁性可牺牲语法
- 避免提及文件名、测试、类型检查、lint、分支名称、PR机制和截图路径

Blocked Or Inconclusive Tracker Work

受阻或无结论的跟踪器工作

If the task was blocked before meaningful progress, either skip the comment or post a short blocker note only if that helps the tracker owner.

如果任务在取得有意义进展前受阻，要么跳过评论，要么仅发布简短的障碍说明（如果这对跟踪器所有者有帮助）。

Success Criteria

成功标准

Source-of-truth context was read first.
Relevant local instructions and code patterns were read before editing.
Tracker items were fetched and summarized correctly when provided.
Video attachments or screen recordings were turned into normalized
```
<video-transcripts>
```
evidence before implementation when tracker evidence required it.
Bare GitHub issues like
```
#555
```
were resolved against the current
```
gh
```
repo instead of guessed.
The chosen implementation fixed the highest-leverage seam available, not just the nearest symptom.
Code-changing tasks that did not already start on a branch clearly dedicated to the same task checked out
```
main
```
and pulled latest before branching.
Non-trivial work loaded
```
planning-with-files
```
or the repo-equivalent planning workflow before implementation.
Non-trivial package or registry work recorded release-artifact requirements in the plan early: changeset for published package work,
```
docs/components/changelog.mdx
```
for registry-only work.
Testing work loaded the testing policy before implementation.
Only the necessary skills were loaded.
The implementation matched the task type instead of following a one-size-fits-all ritual.
Batch work did not sprawl across multiple slices without explicit instruction.
Verification matched the change scope.
Final handoff matched the task type.
Testing or batch handoff reported the completed slice, verification, and remaining queue when relevant.
Any tracker, browser, review, or compound follow-up was done only if actually relevant.

首先阅读了可信源上下文。
编辑前阅读了相关本地说明和代码模式。
提供跟踪器项时，正确获取并总结了内容。
当跟踪器证据要求时，在实现前将视频附件或屏幕录制转换为标准化
```
<video-transcripts>
```
证据。
纯GitHub issue如
```
#555
```
在当前
```
gh
```
仓库中解析，而非猜测。
选择的实现修复了可用的最高价值层级，而非仅修复最接近的症状。
未在明确专用分支上开始的代码变更任务，在分支前切换到
```
main
```
并拉取最新代码。
非琐碎工作在实现前加载了
```
planning-with-files
```
或仓库等效的规划工作流。
非琐碎包或注册表工作在规划早期记录了发布工件要求：已发布包工作需要changeset，仅注册表工作需要更新
```
docs/components/changelog.mdx
```
。
测试工作在实现前加载了测试策略。
仅加载了必要的技能。
实现与任务类型匹配，而非遵循一刀切的流程。
批量工作未在无明确指令的情况下扩展到多个片段。
验证与变更范围匹配。
最终交接与任务类型匹配。
测试或批量交接报告了已完成的片段、验证操作和仍在队列中的内容（如适用）。
仅在实际相关时进行了跟踪器、浏览器、评审或复合后续操作。