oneshot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OneShot

Critical — Label hygiene

关键要求——标签清理规范

Internal planning labels are author coordinates, not reader coordinates. Strip them from every shipped artifact this skill emits — code, comments, commit subjects/bodies, PR titles/descriptions, release notes, doc paragraphs, non-trivial comments.

Workstream and task labels —
```
WS-N
```
,
```
Phase-A
```
,
```
Step-3
```
, issue or ticket numbers, plan phase names from the source spec, issue body, or planning artifact. Translate to the domain noun (
```
Runs the battery script (WS-2)
```
→
```
Runs the battery script
```
).
Process language — "the rebuild", "the prior
```
<file>
```
", "carried verbatim from", "the cleanup pass", "the audit", "spec AC" standalone. Replace with the concrete fact (
```
carries the routing from the prior aggregation
```
→
```
routes via the merge keys in the synthesis module
```
).
Plan-internal references — "as the brief says", "per the workstream", "from the forge artifact". Drop the reference; state the fact directly.

Carve-outs — literal

WS-N

is legitimate where the skill IS the format authority (forge templates, apex rule documentation). Reviewer-facing dev docs (e.g.

MIGRATION.md

under

tests/<skill>/

) may reference deleted artifacts by their author-time names.

内部规划标签是作者的标识，而非面向读者的标识。该技能生成的所有交付产物（代码、注释、提交主题/正文、PR标题/描述、发布说明、文档段落、非琐碎注释）都需移除这类标签。

工作流与任务标签——
```
WS-N
```
、
```
Phase-A
```
、
```
Step-3
```
、问题或工单编号、源规格、问题正文或规划产物中的计划阶段名称。需转换为领域名词（例如
```
Runs the battery script (WS-2)
```
→
```
Runs the battery script
```
）。
流程术语——“the rebuild”“the prior
```
<file>
```
”“carried verbatim from”“the cleanup pass”“the audit”“spec AC”这类独立表述。需替换为具体事实（例如
```
carries the routing from the prior aggregation
```
→
```
routes via the merge keys in the synthesis module
```
）。
计划内部引用——“as the brief says”“per the workstream”“from the forge artifact”。需移除引用，直接陈述事实。

例外情况——当该技能本身是格式权威时（例如forge模板、apex规则文档），字面形式的

WS-N

是合法的。面向评审者的开发文档（例如

tests/<skill>/

下的

MIGRATION.md

）可以按作者命名方式引用已删除的产物。

Important — Writing rules

重要规则——写作规范

These rules govern every prose artifact this skill emits — READMEs, CHANGELOGs, commit messages, PR bodies, release notes, doc paragraphs, non-trivial comments. Apply them at draft time, verify before output.

Match the surrounding style — punctuation, capitalization, backtick conventions, em-dash vs parens, bullet style.
Every sentence changes the reader's understanding. Cut it otherwise.
Front-load the verb — "Creates", not "This helps you create".
Concrete over abstract. Lists for ≥3 enumerable items.
Assert positively. Reserve negation for real constraints (
```
NEVER commit secrets
```
).
No marketing words: powerful, robust, seamlessly, leverage, unlock, comprehensive, delightful.
No AI tells: delve, tapestry, intricate, pivotal, testament, underscore, crucial, garner, showcase, additionally, moreover, furthermore, indeed.
After drafting English prose, invoke
```
/humanize-en
```
if installed.

Implement

$ARGUMENTS

at maximum speed. Ship fast, iterate later.

这些规则适用于该技能生成的所有文字产物——README、CHANGELOG、提交信息、PR正文、发布说明、文档段落、非琐碎注释。需在草稿阶段应用，输出前验证。

匹配周边风格——标点、大小写、反引号约定、破折号与括号的使用、项目符号样式。
每句话都要改变读者的认知，否则删除。
动词前置——使用“Creates”而非“This helps you create”。
优先具体表述，避免抽象。≥3个可枚举项使用列表形式。
正面陈述。仅对实际限制使用否定表述（例如
```
NEVER commit secrets
```
）。
禁用营销词汇：powerful、robust、seamlessly、leverage、unlock、comprehensive、delightful。
禁用AI式书面语：delve、tapestry、intricate、pivotal、testament、underscore、crucial、garner、showcase、additionally、moreover、furthermore、indeed。
英文草稿完成后，若已安装则调用
```
/humanize-en
```
。

以最快速度实现

$ARGUMENTS

。快速交付，后续迭代。

Workflow

工作流

0. Resolve input

0. 解析输入

If the input looks like a GitHub issue reference (

#N

owner/repo#N

, or a GitHub URL like

https://github.com/.../issues/N

Fetch the issue:

#N

→

gh issue view <N> --json title,body,labels

(current repo).

owner/repo#N

or full URL →

gh issue view <N> --repo owner/repo --json title,body,labels

Use the issue title + body as the task description.
If the issue body has task lists or acceptance criteria, use them as the implementation checklist.

Then proceed to EXPLORE with the resolved description.

若输入看起来是GitHub问题引用（

#N

、

owner/repo#N

，或类似

https://github.com/.../issues/N

的GitHub URL）：

获取问题详情：

#N

→

gh issue view <N> --json title,body,labels

（当前仓库）。

owner/repo#N

或完整URL →

gh issue view <N> --repo owner/repo --json title,body,labels

。

使用问题标题+正文作为任务描述。
若问题正文包含任务列表或验收标准，将其作为实现检查清单。

之后使用解析后的描述进入EXPLORE阶段。

1. Explore (minimal)

1. 探索（极简模式）

Gather the minimum context needed to identify the edit target. Direct tools first — no subagent overhead on the happy path:

```
Glob
```
for 2-3 files by pattern.
```
Grep
```
for specific symbols or strings.
Quick
```
WebSearch
```
only if library-specific API knowledge is missing.

When to spawn an
Explore
subagent instead: if one or two direct searches don't locate the edit target, stop searching and spawn a single

Explore

subagent with a specific question ("find the file that handles {X}"). Reason: multiple rounds of Glob/Grep pollute the main context with file contents you'll never edit — a subagent returns just the answer. This is an exception path, not the default.

No exploration tours. As soon as the edit target is identified, move on.

收集确定编辑目标所需的最少上下文。优先使用直接工具——正常流程下不启用子代理：

使用
```
Glob
```
按模式查找2-3个文件。
使用
```
Grep
```
查找特定符号或字符串。
仅当缺少库特定API知识时，才进行快速
```
WebSearch
```
。

**何时改用

Explore

子代理：**如果1-2次直接搜索无法定位编辑目标，停止搜索并生成一个带有特定问题的

Explore

子代理（例如“find the file that handles {X}”）。原因：多次Glob/Grep会将永远不会编辑的文件内容污染主上下文——子代理仅返回答案。这是异常路径，而非默认流程。

不进行全面探索。一旦确定编辑目标，立即进入下一阶段。

1b. Complexity check (circuit breaker)

1b. 复杂度检查（断路器机制）

After exploring, assess whether this task actually fits oneshot. Flag if any of these signals appear:

> 5 files need modification
> 2 distinct systems/domains involved (auth + billing + notifications, etc.)
Cross-cutting concerns (database migrations, API changes with client updates, etc.)
Unclear requirements — the task seemed simple but the codebase reveals hidden complexity

If triggered: stop and warn the user before coding.

This task is more complex than it looks:
- {specific reason: e.g., "touches 8 files across 3 modules"}
- {specific reason}

Recommendations:
- /apex {task}        — structured implementation with analysis and planning
- /forge -s {task}    — think, decide, and plan first

Continue with /oneshot anyway? (results may be incomplete)

Wait for user confirmation. Their call — if they continue, proceed. If not, stop.

If not triggered: proceed directly to CODE. No delay on the happy path.

探索完成后，评估任务是否真的适合oneshot模式。若出现以下任一信号，触发告警：

需要修改超过5个文件
涉及超过2个独立系统/领域（例如认证+计费+通知等）
存在跨领域关注点（例如数据库迁移、需要客户端更新的API变更等）
需求不明确——任务看似简单，但代码库揭示了隐藏的复杂度

**若触发：**编码前停止操作并向用户发出警告。

This task is more complex than it looks:
- {specific reason: e.g., "touches 8 files across 3 modules"}
- {specific reason}

Recommendations:
- /apex {task}        — structured implementation with analysis and planning
- /forge -s {task}    — think, decide, and plan first

Continue with /oneshot anyway? (results may be incomplete)

等待用户确认。由用户决定——若用户选择继续，则推进；否则停止。

**若未触发：**直接进入CODE阶段。正常流程下不延迟。

2. Code

2. 编码

Execute the changes immediately:

Follow existing codebase patterns exactly.
Clear variable and method names over comments.
Stay strictly in scope — change only what the task requires.

立即执行变更：

严格遵循现有代码库的模式。
优先使用清晰的变量和方法名，而非注释。
严格保持在任务范围内——仅修改任务要求的内容。

3. Test

3. 测试

Run the project's lint and typecheck commands — discover them from project instructions (

CLAUDE.md

AGENTS.md

, or equivalent),

package.json

scripts for JS/TS,

pyproject.toml

Cargo.toml

go.mod

for other ecosystems.

If they fail, fix only what you broke and re-run.
No full test suite unless the user explicitly asks.

运行项目的代码检查和类型校验命令——从项目说明文档（

CLAUDE.md

、

AGENTS.md

或同类文档）、JS/TS项目的

package.json

脚本、其他生态的

pyproject.toml

Cargo.toml

go.mod

中查找相关命令。

若命令执行失败，仅修复自己造成的问题后重新运行。
除非用户明确要求，否则不运行完整测试套件。

Output

输出

On success

成功时

undefined

undefined

Done

Task: {what was implemented} Files changed: {list} Validation: ✓ lint ✓ typecheck

undefined

Task: {what was implemented} Files changed: {list} Validation: ✓ lint ✓ typecheck

undefined

On blocker (stuck after 2 attempts, or circuit breaker declined)

遇到阻塞时（尝试2次后仍卡住，或用户拒绝断路器建议）

undefined

undefined

Blocked

Task: {what was attempted} Attempts: {N} Blocker: {specific failure or unknown} Recommendation: /apex {task} ← restart with structured analysis

undefined

Task: {what was attempted} Attempts: {N} Blocker: {specific failure or unknown} Recommendation: /apex {task} ← restart with structured analysis

undefined

Constraints

约束

One task only — no tangential improvements, no "while I'm here" additions.
No comments unless the logic is genuinely non-obvious.
No refactoring outside the immediate scope.
No documentation files unless the user asks.
Stuck after 2 attempts — report the blocker and stop. Don't thrash.

仅处理单个任务——不进行无关改进，不添加“顺便完成”的内容。
不添加注释——除非逻辑确实难以理解。
不进行重构——超出当前任务范围的重构不做。
不修改文档文件——除非用户明确要求。
尝试2次后仍卡住——报告阻塞并停止。不要反复尝试。

Gotchas

注意事项

Circuit-breaker after Explore needs explicit user approval to continue. When the task spans >5 files, >2 systems, or hits cross-cutting concerns, the skill stops post-Explore and surfaces the complexity check. The model sometimes treats the "Recommendation: /apex" line as a verdict and auto-restarts instead of asking. Fix: when the breaker trips, present the scope to the user and wait. Re-entry into oneshot for a complex task tends to thrash.
gh
unauthenticated = silent issue-ref fail. A
```
#42
```
or
```
owner/repo#42
```
reference is fetched via
```
gh issue view
```
; an unauthenticated
```
gh
```
returns empty output, and the model proceeds with no task context. Fix: run
```
gh auth status
```
before invoking with an issue ref; or paste the issue body directly as the task description.
Stuck-after-2-attempts is NOT auto-escalated to
/apex
. The Blocked output names the recommendation but does not invoke it. The model sometimes interprets the recommendation as "Claude should run it next." Fix: when oneshot reports Blocked, the user manually runs
```
/apex {task}
```
(or
```
/forge
```
first for ambiguity). Escalation is a user action, not an automatic handoff.

探索阶段触发断路器后需获得用户明确批准才能继续。当任务涉及超过5个文件、超过2个系统，或存在跨领域关注点时，技能会在探索阶段结束后停止并提示复杂度检查。模型有时会将“Recommendation: /apex”视为结论并自动重启，而非等待用户确认。解决方法：触发断路器时，向用户展示任务范围并等待。针对复杂任务重新进入oneshot模式往往会导致无效尝试。
gh
未认证会导致问题引用静默失败。
```
#42
```
或
```
owner/repo#42
```
引用通过
```
gh issue view
```
获取；未认证的
```
gh
```
会返回空输出，模型会在无任务上下文的情况下继续执行。解决方法：调用问题引用前运行
```
gh auth status
```
；或直接将问题正文作为任务描述粘贴。
尝试2次后卡住不会自动升级到
/apex
。阻塞输出会给出推荐，但不会自动调用。模型有时会将推荐理解为“Claude应继续执行”。解决方法：当oneshot报告阻塞时，用户需手动运行
```
/apex {task}
```
（或先使用
```
/forge
```
处理模糊需求）。升级是用户操作，而非自动移交。