issues

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Issues

Command-driven GitHub issue skill. Parse the first token as a command when it matches the table below; otherwise map clear intent.

Default: if the user gives only an issue identifier (

#42

, URL) and optional details (context, constraints, “fix the flaky test”) — no admin command — execute Complete the work. Do not ask which admin command to run. Do not stop at

status

critique

refine

Admin commands shape the issue when explicitly requested; they are not the default path.

命令驱动的GitHub Issue处理Skill。当第一个词匹配下表中的命令时，将其解析为命令；否则根据明确意图映射对应操作。

默认规则：如果用户仅提供Issue标识符（

#42

、

、URL）和可选详情（上下文、约束、“修复不稳定的测试”）——未指定管理命令——则执行完成工作流程。不要询问要运行哪个管理命令。不要停留在

status

critique

refine

步骤。

管理命令仅在显式请求时用于调整Issue，不是默认路径。

Operating contract

操作规范

Shared by every DecisionNerd/dev-skills skill. Canonical copy:

handbook/concepts/14-operating-contract.md

Define done first. Before using tools, write the finish line in one or two lines: the acceptance criteria (existing issue AC, BDD scenarios, tests, or contract when they exist; otherwise propose them and say where they should live) and the evidence that will prove them. Re-check it before reporting done. Never report done on work you did not verify.
Requested scope sets the finish line. A question ("is it ready?", "why is it broken?", "what next?") ends with the answer and a
```
Next:
```
line naming the exact next invoke. An outcome request ("fix", "finish", "land", "#42") continues through the chain (diagnose → fix → test → check-readiness → merge-it) until the outcome or a real blocker. Do not end a turn with "Do you want me to…?" for in-scope, in-repo work.
Stop only for real blockers. Stop and ask only when you cannot continue without the user, or before: deleting data or unmerged work, force-push or history rewrite, changing anything outside this repository (GitHub objects, deployments, live data, production or paid resources, external services), or leaving the requested scope, unless the user's request already named that exact action. Keep the harness's permission prompts for risky commands. Otherwise keep going and put status notes in the same message as the next action.
Ask well, once. For a genuine question use the harness's structured question tool when it has one (Claude Code:
```
AskUserQuestion
```
; Codex:
```
request_user_input
```
when the current mode supports it) with concrete options; otherwise plain text with numbered options. Treat the answer as settled; do not re-open earlier verdicts, plans, or answers unless asked.
Fan out when work is parallel. Use subagents for independent reads (repo survey, evidence gathering, per-option research, per-area audits) and for independent verification (a reviewer that did not write the change). Writes stay single-owner per path set and sequential. Brief every child with goal, done-when, constraints, must-not, and return shape; verify each child's result before consolidating. Use Claude Code's
```
Workflow
```
tool only for orchestration across many subagents that truly needs it; it is expensive.
Pick the model tier per child; defer to routing config. If the harness or user config already routes subagents (Claude Code
```
CLAUDE_CODE_SUBAGENT_MODEL
```
or a CLAUDE.md rule; Codex
```
agents.default_subagent_model
```
or a role's
```
agents.<name>.config_file
```
; Cursor a custom subagent's
```
model:
```
frontmatter), follow it and do not pass a model. Otherwise: mechanical search or inventory → fast/cheap (Claude Code
```
haiku
```
); implementation and evidence gathering → mid (
```
sonnet
```
); planning, review, adversarial verification → top (
```
opus
```
or
```
fable
```
). In Claude Code set it with the
```
Agent
```
tool
```
model
```
param or agent frontmatter
```
model:
```
; in Codex pass a spawn model or set
```
model
```
in the role's config file; in Cursor set
```
model:
```
(default
```
inherit
```
) in
```
.cursor/agents/*.md
```
. Where the harness cannot choose, children inherit the parent model or the harness picks one (Cursor's built-in Explore/Bash/Browser subagents pick per subtask); say which in the status note.
Keep a checklist on long runs. For more than about five steps or work that crosses skills, keep
```
TASKS.md
```
at the repo root and tick items as they finish. Do not commit it unless the repo already tracks one.
Close every run with three headings.
```
Blocked on me
```
(the one genuine question or blocker, else "none");
```
Changed
```
(files, commits, GitHub objects, deploys, else "nothing");
```
Found
```
(evidence, verdict, and
```
Next: <exact invoke>
```
).

所有DecisionNerd/dev-skills Skill均遵循此规范。标准副本：

handbook/concepts/14-operating-contract.md

。

先定义完成标准。使用工具前，用一两行说明完成线：验收标准（现有Issue的AC、BDD场景、测试或契约，若存在；否则提出建议并说明应存放的位置）以及证明完成的证据。报告完成前重新核对。未经验证的工作绝不报告完成。
请求的范围决定完成边界。问题类请求（“准备好了吗？”、“为什么坏了？”、“下一步是什么？”）以答案和
```
Next:
```
行结束，该行明确下一次调用的具体内容。结果类请求（“修复”、“完成”、“上线”、
```
#42
```
）将沿流程链推进（诊断→修复→测试→就绪检查→合并），直到达成目标或遇到真正的阻塞。对于仓库范围内的工作，不要以“你想让我…吗？”结束本轮回复。
仅遇真正阻塞时停止。仅当无法在没有用户参与的情况下继续，或在执行以下操作前才停止并询问：删除数据或未合并的工作、强制推送或历史重写、修改此仓库之外的任何内容（GitHub对象、部署、实时数据、生产或付费资源、外部服务），或超出请求范围，除非用户的请求已明确指定该确切操作。保留宿主工具对风险命令的权限提示。否则继续推进，并在同一条消息中附上状态说明和下一步操作。
一次问清楚。对于真实问题，若宿主工具支持结构化提问工具（Claude Code：
```
AskUserQuestion
```
；Codex：当前模式支持时使用
```
request_user_input
```
），则使用该工具并提供具体选项；否则使用带编号选项的纯文本。将答案视为最终结论；除非被要求，否则不要重新讨论之前的结论、计划或答案。
并行工作时分派处理。对于独立的读取操作（仓库调研、证据收集、逐选项研究、各领域审计）和独立验证（由未编写变更的评审子Agent执行），使用子Agent。写入操作在每条路径上保持单一负责人并顺序执行。向每个子Agent明确说明目标、完成条件、约束、禁止事项和返回格式；合并结果前验证每个子Agent的输出。仅当确实需要编排大量子Agent时才使用Claude Code的
```
Workflow
```
工具；该工具成本较高。
为每个子Agent选择模型等级；优先遵循路由配置。如果宿主工具或用户配置已为子Agent设置路由（Claude Code的
```
CLAUDE_CODE_SUBAGENT_MODEL
```
或CLAUDE.md规则；Codex的
```
agents.default_subagent_model
```
或角色的
```
agents.<name>.config_file
```
；Cursor自定义子Agent的
```
model:
```
前置元数据），则遵循该配置，不要传递模型参数。否则：机械搜索或盘点→快速/低成本（Claude Code
```
haiku
```
）；实现和证据收集→中等（
```
sonnet
```
）；规划、评审、对抗性验证→顶级（
```
opus
```
或
```
fable
```
）。在Claude Code中通过
```
Agent
```
工具的
```
model
```
参数或Agent前置元数据的
```
model:
```
设置；在Codex中传递生成模型或在角色配置文件中设置
```
model
```
；在Cursor中在
```
.cursor/agents/*.md
```
中设置
```
model:
```
（默认
```
inherit
```
）。若宿主工具无法选择模型，子Agent将继承父Agent模型或由宿主工具选择（Cursor内置的Explore/Bash/Browser子Agent会根据子任务选择）；在状态说明中注明使用的模型。
长流程运行时保留检查清单。对于超过约五个步骤或跨Skill的工作，在仓库根目录维护
```
TASKS.md
```
，完成项打勾。除非仓库已跟踪该文件，否则不要提交。
每次运行结束时包含三个标题。
```
Blocked on me
```
（我这边的阻塞：一个真实问题或阻塞项，否则为“无”）；
```
Changed
```
（变更内容：文件、提交、GitHub对象、部署，否则为“无”）；
```
Found
```
（发现内容：证据、结论，以及
```
Next: <具体调用内容>
```
）。

Commands

命令

Command	What it does
`create` / `draft`	New issue from a rough idea (duplicate check, questions, draft, approve)
`update`	Improve an existing issue body/title/metadata with approval
`critique`	Honest quality critique (clarity, scope, AC, BDD, risks, docs)
`narrow`	Shrink scope; move extras to Non-Goals / follow-ups
`widen`	Expand scope deliberately with rationale and still-bounded AC
`merge`	Combine overlapping issues into one canonical issue (close/redirect others)
`clean`	Remove noise, stale text, broken checklists, formatting cruft
`refine`	Sharpen wording and structure without changing agreed scope
`explain`	Plain-language explanation for the user (not a GitHub edit)
`document`	Improve or add repo docs that the issue needs (then link from the issue)
`close`	Close with evidence-based rationale (and comment when useful)
`reopen`	Reopen with reason
`search` / `dup`	Duplicate/related issue search only
`status`	Summarize state, labels, milestone, linked PRs, blockers
`help` / `library`	List commands

Target: issue number (

#123

), URL, title search, or free-text idea (for

create

命令	功能
`create` / `draft`	从粗略想法创建新Issue（重复检查、提问、草稿、审批）
`update`	经审批后改进现有Issue的正文/标题/元数据
`critique`	客观质量评审（清晰度、范围、AC、BDD场景、风险、文档）
`narrow`	缩小范围；将额外内容移至非目标/后续跟进
`widen`	有依据地扩大范围，同时保持AC边界清晰
`merge`	将重叠的Issue合并为一个标准Issue（关闭/重定向其他Issue）
`clean`	移除噪音、过时文本、损坏的检查清单、格式冗余
`refine`	在不改变已约定范围的前提下优化措辞和结构
`explain`	为用户提供通俗易懂的解释（不修改GitHub内容）
`document`	改进或补充Issue所需的仓库文档（然后在Issue中添加链接）
`close`	基于证据说明理由后关闭（必要时添加评论）
`reopen`	说明理由后重新打开
`search` / `dup`	仅搜索重复/相关Issue
`status`	汇总状态、标签、里程碑、关联PR、阻塞项
`help` / `library`	列出所有命令

目标：Issue编号（

、

#123

）、URL、标题搜索，或自由文本想法（用于

create

）。

Routing

路由规则

No argument: ask via the structured question tool — options: complete an issue (needs
```
#N
```
) /
```
create
```
/
```
status
```
/
```
help
```
.
First word is a command: run that command; remainder is the target/context. After admin work, state
```
Next: issues #N
```
and run it when the user signaled progress.
Clear admin intent without command word (“narrow #42”, “explain this issue”, “draft an issue for…”): map to that command and proceed.
Issue identifier ± details, no admin command (
```
#42
```
,
```
42
```
, URL, or
```
#42 focus on the API path
```
): Complete the work — execute, don’t menu.
Rough idea / bug / feature with no identifier and no command:
```
create
```
.

Before mutating GitHub (create/update/close/reopen/merge redirects), state the proposed change; ask one structured question with options

<do it> / revise / stop

. Skip when the user’s request already named that exact action. Implementation and other completion handoffs follow the target skill’s approval rules.

无参数：通过结构化提问工具询问——选项：完成Issue（需要
```
#N
```
）/
```
create
```
/
```
status
```
/
```
help
```
。
第一个词是命令：运行该命令；剩余内容为目标/上下文。管理工作完成后，说明
```
Next: issues #N
```
，并在用户表示要推进时执行。
有明确管理意图但无命令词（“缩小#42的范围”、“解释这个Issue”、“为…起草一个Issue”）：映射到对应命令并继续。
有Issue标识符 ± 详情，无管理命令（
```
#42
```
、
```
42
```
、URL，或
```
#42 关注API路径
```
）：完成工作——直接执行，不要显示菜单。
无标识符、无命令的粗略想法/ Bug /功能需求：走
```
create
```
流程。

在修改GitHub内容（创建/更新/关闭/重新打开/合并重定向）之前，说明拟议的变更；提出一个结构化问题，选项为

<执行>

/ 修改 / 停止。如果用户的请求已明确指定该确切操作，则跳过此步骤。实现和其他完成流程的交接遵循目标Skill的审批规则。

Shared operations

共享操作

Use references/ops.md for

critique

narrow

widen

merge

clean

refine

explain

, and

document

critique

、

narrow

、

widen

、

merge

、

clean

、

refine

、

explain

和

document

操作请参考references/ops.md。

Create / draft

创建/草稿

For

create

draft

, follow references/create.md end-to-end (disposition → questions → draft → approval →

gh issue create

/ update).

对于

create

或

draft

，全程遵循references/create.md（处理→提问→草稿→审批→

gh issue create

/ 更新）。

Complete the work

完成工作

Issue admin (

create

critique

refine

narrow

/ …) tracks intent. Completing the work means planning, diagnosing, implementing, proving, and shipping.

Issue管理（

create

critique

refine

narrow

/ …）用于跟踪意图。完成工作意味着规划、诊断、实现、验证和上线。

Planning and workspace rules

规划与工作区规则

Planning is a read-only phase, not a requirement for a host-specific mode or tool. If native Plan Mode is unavailable, inspect and produce the plan in the current agent. Respect active host restrictions; do not invent a mode-switch tool or stop merely because one is absent. A completion request already authorizes in-scope planning and implementation when the host permits them; a planning-only request does not.

Before the first repository write, read and follow references/workspace.md. Use a dedicated task worktree by default, with one writer per worktree. Reuse a host-created task worktree only after verifying ownership. Apply this to docs and tests as well as code; read-only planning and GitHub-only admin do not need a worktree. Carry the absolute worktree path, branch, base, and ownership through every execution-skill handoff.

规划是只读阶段，不是特定宿主模式或工具的必需项。如果原生规划模式不可用，在当前Agent中检查并生成计划。遵守宿主的活跃限制；不要发明模式切换工具，也不要仅因为缺少该工具就停止。当宿主允许时，完成类请求已授权范围内的规划和实现；仅规划类请求则不授权。

首次写入仓库之前，请阅读并遵循references/workspace.md。默认使用专用任务工作树，每个工作树仅一个写入者。仅在验证所有权后才能复用宿主创建的任务工作树。此规则适用于文档、测试以及代码；只读规划和仅GitHub管理操作不需要工作树。在每次执行Skill交接时传递工作树绝对路径、分支、基准和所有权信息。

Default path (identifier ± details)

默认路径（标识符 ± 详情）

When routed here (no admin command):

State the issue's AC and BDD completion scenarios as the finish line before picking an execution skill. For multi-issue or multi-area work, fan out one subagent per non-overlapping path set (mid tier) and keep

TASKS.md

for chains longer than five steps.

Resolve the issue (
```
gh issue view
```
); skim linked PRs, milestone, labels.
Fold any user details into scope (constraints, focus area, “don’t touch X”).
Resolve repository policy and inspect existing worktrees/PRs. Before implementation, establish the owned workspace using the rules above; plan-only work remains read-only.
Pick the smallest next execution skill from the table and run it now (invoke that skill / continue the work). One-line why is enough — do not present a recommend-only menu.
Chain forward as each step unblocks (e.g.
```
recon issue
```
→ implement →
```
check-readiness
```
→
```
merge-it
```
) until a real blocker (an outside-repo approval, missing info) or the user stops you.
If the issue body is too vague to execute safely, do the minimum shaping (
```
refine
```
questions or a tight
```
recon issue
```
plan), then continue execution — don’t end on admin alone.

当路由到此处时（无管理命令）：

在选择执行Skill之前，先说明Issue的AC和BDD完成场景作为完成线。对于多Issue或多领域的工作，为每组不重叠的路径分派一个子Agent（中等模型），对于超过五步的流程链维护

TASKS.md

。

解析Issue（
```
gh issue view
```
）；浏览关联PR、里程碑、标签。
将用户提供的所有详情纳入范围（约束、关注领域、“不要修改X”）。
确认仓库策略，检查现有工作树/PR。实现之前，根据上述规则建立专属工作区；仅规划工作保持只读。
从下表中选择最小的下一步执行Skill并立即运行（调用该Skill / 继续工作）。只需一行说明理由——不要仅提供推荐菜单。
每一步解除阻塞后继续链式推进（例如
```
recon issue
```
→ 实现 →
```
check-readiness
```
→
```
merge-it
```
），直到遇到真正的阻塞（仓库外的审批、信息缺失）或用户停止。
如果Issue正文过于模糊，无法安全执行，则进行最小程度的调整（
```
refine
```
提问或紧凑的
```
recon issue
```
规划），然后继续执行——不要仅停留在管理步骤。

After explicit admin commands

显式执行管理命令之后

After

status

critique

explain

create

draft

(once the issue exists), state

Next: issues #N

(or the skill from the table that best fits the current state); run it when the user already signaled progress (“ship it”, “finish this”, or details that imply do-the-work).

Situation	Execute
Needs implementation plan	`recon issue #N` (then implement from the plan)
Live UI / product broken	`troubleshoot-app` (diagnoses and fixes in-repo)
Backend / API / algo bug	`diagnose-bug` (diagnoses and fixes in-repo)
Repair plan from diagnosis	`fix-it`
Need tests / BDD evidence	`test-it`
Need logs/metrics/traces	`observe-it`
Repo docs gap (not just issue body)	`document-it`
Options before building	`research-it`
Scope satisfied? Pre-PR / close	`check-readiness`
Open PR / CI / merge / close issue	`merge-it` (or `pulls` when merge-only)
Milestone membership / release slice	then return to critical-path issue execution
Unsure / lost	`recon` (no args) or `idk-now`

Do not default to

issues refine|critique|narrow|status

when an identifier was given. Prefer execute (

recon issue

/ diagnose / fix / implement /

merge-it

) over more issue editing.

在

status

、

critique

、

explain

、

create

draft

（Issue已创建）之后，说明

Next: issues #N

（或最符合当前状态的Skill）；如果用户已表示要推进（“上线”、“完成这个”，或暗示要执行工作的详情），则直接运行。

场景	执行Skill
需要实现计划	`recon issue #N` （然后根据计划实现）
线上UI / 产品故障	`troubleshoot-app` （诊断并修复仓库内问题）
后端 / API / 算法Bug	`diagnose-bug` （诊断并修复仓库内问题）
根据诊断制定修复计划	`fix-it`
需要测试 / BDD证据	`test-it`
需要日志/指标/链路追踪	`observe-it`
仓库文档缺口（不仅是Issue正文）	`document-it`
构建前的选项调研	`research-it`
范围是否满足？PR前 / 关闭前	`check-readiness`
开放PR / CI / 合并 / 关闭Issue	`merge-it` （或仅合并时用 `pulls` ）
里程碑归属 / 发布切片	然后返回关键路径Issue执行
不确定 / 迷失方向	`recon` （无参数）或 `idk-now`

不要在提供了标识符的情况下默认走

issues refine|critique|narrow|status

。优先执行（

recon issue

/ 诊断 / 修复 / 实现 /

merge-it

）而非更多Issue编辑。

Update / close / reopen / search / status

更新 / 关闭 / 重新打开 / 搜索 / 状态

Resolve the issue with
```
gh issue view
```
/ search; read
```
AGENTS.md
```
for repo conventions.
```
update
```
: propose a diff of sections; apply only after approval (
```
gh issue edit
```
or comment).
```
close
```
/
```
reopen
```
: state why; comment when it preserves decision history.
```
search
```
/
```
dup
```
: classify Duplicate / Related / No Match; prefer update-over-create.
```
status
```
: short factual summary; state
```
Next: issues #N
```
(run it when the user asked to finish/ship).

使用
```
gh issue view
```
/ 搜索解析Issue；阅读
```
AGENTS.md
```
了解仓库约定。
```
update
```
：提出各部分的变更差异；仅在审批后应用（
```
gh issue edit
```
或评论）。
```
close
```
/
```
reopen
```
：说明原因；当有助于保留决策历史时添加评论。
```
search
```
/
```
dup
```
：分类为重复 / 相关 / 不匹配；优先更新而非创建。
```
status
```
：简短的事实汇总；说明
```
Next: issues #N
```
（如果用户要求完成/上线则运行）。

Output

输出

Blocked on me

none

无

Changed

nothing

无

Found

Next: issues #N (or the execution skill that best fits the current state)

Next: issues #N（或最符合当前状态的执行Skill）

Related skills

Grounding

基础依据

This skill’s TTPs are grounded in current engineering baselines (DORA, GitHub Docs, Fowler/Beck, Google SRE & SWE book, OpenTelemetry, OWASP LLM / NIST AI RMF, Diátaxis — see handbook

sources.md

GitHub Issues as tracked intent — bug-council list (

handbook/concepts/12-bugs-and-debt.md

) plus lightweight BDD completion scenarios on the quality trace (

13-quality-trace.md

). Narrow scope = small batches (DORA). Label debt type; map scenarios to evidence.

Handbook card:

handbook/practices/issues.md

本Skill的TTPs基于当前工程基线（DORA、GitHub Docs、Fowler/Beck、Google SRE & SWE书籍、OpenTelemetry、OWASP LLM / NIST AI RMF、Diátaxis——参见手册

sources.md

）。

GitHub Issues作为跟踪的意图——Bug评审列表（

handbook/concepts/12-bugs-and-debt.md

）加上质量追踪上的轻量级BDD完成场景（

13-quality-trace.md

）。小范围 = 小批量（DORA）。标记债务类型；将场景与证据对应。

手册卡片：

handbook/practices/issues.md

。

issues

Original

Translation

Issues

Issues

Operating contract

操作规范

Commands

命令

Routing

路由规则

Shared operations

共享操作

Create / draft

创建/草稿

Complete the work

完成工作

Planning and workspace rules

规划与工作区规则

Default path (identifier ± details)

默认路径（标识符 ± 详情）

After explicit admin commands

显式执行管理命令之后

Update / close / reopen / search / status

更新 / 关闭 / 重新打开 / 搜索 / 状态

Output

输出

Blocked on me

Blocked on me

Changed

Changed

Found

Found

Related skills

相关Skill

Grounding

基础依据