deploy-fix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deploy Fix Skill

Diagnose a build, CI, or deployment failure, choose the safest repair path, and fix it — classify complexity first, then either fix directly or track progress through structured phases.

<request_routing>

诊断构建、CI或部署失败，选择最安全的修复路径并完成修复——先分类复杂度，然后直接修复或通过结构化阶段跟踪进度。

<request_routing>

Positive triggers

触发条件（正向）

A build command fails with a concrete error such as
```
Module not found
```
, type errors, or compilation failures.
A CI pipeline step fails with a specific error in logs (lint, test, build, or deploy stage).
A deployment fails with a concrete error such as function timeout, missing env vars, or platform-specific build errors.
A specific folder or workspace within a monorepo fails to build.

构建命令因具体错误失败，例如
```
Module not found
```
、类型错误或编译失败。
CI流水线步骤在日志中出现特定错误（lint、测试、构建或部署阶段）。
部署因具体错误失败，例如函数超时、缺少环境变量或平台特定的构建错误。
单体仓库中的特定文件夹或工作区构建失败。

Out-of-scope

超出范围

Runtime bugs in application code with a reproduction path. Route to
```
bug-fix
```
.
Security audits, exploit review, or trust-boundary analysis. Route to
```
security-review
```
.
New feature work, refactors, or speculative cleanup not tied to a concrete failure.
General performance optimization without a failing build or deploy.

可复现的应用代码运行时bug。转至
```
bug-fix
```
。
安全审计、漏洞审查或信任边界分析。转至
```
security-review
```
。
与具体失败无关的新功能开发、重构或预防性清理工作。
无构建或部署失败的通用性能优化。

Boundary cases

边界情况

If the user asks for root-cause analysis only, stay in diagnosis mode and do not edit.
If a CI failure is caused by a single runtime bug (e.g., a failing test from a code defect), this skill owns the CI-level fix; hand off the underlying code bug to
```
bug-fix
```
if the root cause is application logic.
If the failure spans build + deployment + runtime, own the build/deploy layer and hand off runtime to
```
bug-fix
```
.

</request_routing>

<argument_validation>

If ARGUMENT is missing, ask immediately:

text

What build/CI/deploy failure should be fixed?
- Error message or failing log output
- Build command or CI step that fails
- Full repo build or specific folder/workspace?
- CI provider (GitHub Actions, Vercel, etc.) if applicable
- Regression or new? (Did it work before? When did it start failing?)
- Consistent or intermittent?
- Recent changes, suspect commits, or environment details
- Relevant config files (package.json, tsconfig, CI config, vercel.json, etc.)

</argument_validation>

<mandatory_reasoning>

如果用户仅要求根本原因分析，保持诊断模式，不进行编辑。
如果CI失败是由单个运行时bug导致（例如代码缺陷引发的测试失败），本Skill负责CI层面的修复；若根本原因是应用逻辑，则将底层代码bug移交至
```
bug-fix
```
。
如果故障涵盖构建+部署+运行时，负责构建/部署层的修复，将运行时问题移交至
```
bug-fix
```
。

</request_routing>

<argument_validation>

如果缺少ARGUMENT，立即询问：

text

需要修复哪些构建/CI/部署失败问题？
- 错误信息或失败的日志输出
- 失败的构建命令或CI步骤
- 是整个仓库构建还是特定文件夹/工作区？
- 适用的CI提供商（GitHub Actions、Vercel等）
- 是回归问题还是新问题？（之前是否正常？何时开始失败？）
- 是持续失败还是间歇性失败？
- 最近的变更、可疑提交或环境细节
- 相关配置文件（package.json、tsconfig、CI配置、vercel.json等）

</argument_validation>

<mandatory_reasoning>

Mandatory Sequential Thinking

强制顺序思考

Always run

sequential-thinking

before implementation. Depth scales with complexity:

Simple (3 thoughts): Identify failing step -> determine fix -> verify approach
Medium (5 thoughts): Classify -> reproduce locally -> hypothesize -> compare options -> recommend
Complex (7+ thoughts): Classify -> reproduce -> analyze dependency chain -> check CI config -> hypothesize multiple causes -> compare options -> assess cross-cutting impact -> recommend

Recommended sequence:

Complexity classification
Failure reproduction and log analysis
Root-cause hypotheses
Option comparison
Final recommendation

Before any edit, collect root-cause evidence from build logs, CI output, or deployment logs and reduce the problem to the narrowest failing boundary you can verify.

</mandatory_reasoning>

<complexity_classification>

在实施前必须运行

sequential-thinking

。思考深度随复杂度调整：

简单（3步思考）：识别失败步骤 -> 确定修复方案 -> 验证方法
中等（5步思考）：分类 -> 本地复现 -> 假设原因 -> 比较方案 -> 推荐
复杂（7+步思考）：分类 -> 复现 -> 分析依赖链 -> 检查CI配置 -> 假设多种原因 -> 比较方案 -> 评估跨领域影响 -> 推荐

推荐流程：

复杂度分类
故障复现与日志分析
根本原因假设
方案比较
最终推荐

在进行任何编辑前，从构建日志、CI输出或部署日志中收集根本原因证据，并将问题缩小到可验证的最窄失败边界。

</mandatory_reasoning>

<complexity_classification>

Complexity Classification

复杂度分类

Classify immediately after sequential-thinking:

Complexity	Signals	Examples	Path
Simple	Single file/config, clear error message, obvious root cause, one fix path, low risk	Missing env var, single typo in config, one outdated dependency, clear type error in one file	Fix-now -- proceed directly without flow tracking
Complex	Multiple packages/configs involved, dependency chain issues, CI environment mismatch, fix has side effects across workspaces, multiple valid fix strategies	Cross-workspace type error chain, CI-only failure with no local repro, lockfile conflicts across multiple packages, build succeeds but deploy fails	Tracked -- create `.hypercore/deploy-fix/flow.json`

Announce the classification:

Complexity: [simple/complex] -- [one-line reason]

When uncertain, classify as complex. It is cheaper to track than to lose investigation progress.

</complexity_classification>

<flow_tracking>

完成顺序思考后立即进行分类：

复杂度	特征	示例	处理路径
简单	单个文件/配置、错误信息明确、根本原因明显、仅一种修复路径、低风险	缺少环境变量、配置中的单个拼写错误、单个过时依赖、单个文件中的明确类型错误	立即修复 -- 直接处理，无需流程跟踪
复杂	涉及多个包/配置、依赖链问题、CI环境不匹配、修复会对工作区产生副作用、存在多种有效修复策略	跨工作区类型错误链、仅CI环境出现的本地无法复现的故障、多个包之间的锁文件冲突、构建成功但部署失败	跟踪处理 -- 创建 `.hypercore/deploy-fix/flow.json`

宣布分类结果：

复杂度：[简单/复杂] -- [一句话原因]

若不确定，归类为复杂。跟踪进度比丢失调查进度成本更低。

</complexity_classification>

<flow_tracking>

Flow Tracking (Complex Path Only)

流程跟踪（仅复杂路径）

When classified as complex, initialize the flow:

bash

mkdir -p .hypercore/deploy-fix

Write

.hypercore/deploy-fix/flow.json

and update it as each phase progresses. See

references/flow-schema.md

for the full schema.

当归类为复杂时，初始化流程：

bash

mkdir -p .hypercore/deploy-fix

编写

.hypercore/deploy-fix/flow.json

，并在每个阶段推进时更新。完整模式请参考

references/flow-schema.md

。

Phase progression

阶段推进

Phase	Description	Next
`investigate`	Reproduce failure, analyze logs, isolate root cause	`options`
`options`	Present 2-3 fix options with tradeoffs	`confirm`
`confirm`	Wait for and record user selection	`fix`
`fix`	Implement selected option	`verify`
`verify`	Run build/CI/deploy validation, report outcome	done

阶段	描述	下一阶段
`investigate`	复现故障、分析日志、定位根本原因	`options`
`options`	提供2-3种修复方案及权衡	`confirm`
`confirm`	等待并记录用户选择	`fix`
`fix`	实施选定方案	`verify`
`verify`	运行构建/CI/部署验证，报告结果	完成

Resume support

恢复支持

.hypercore/deploy-fix/flow.json

already exists, read it first and continue from the last incomplete phase (

in_progress

pending

). Do not restart completed phases.

</flow_tracking>

<execution_modes>

Use one of these branches explicitly:

Diagnose-only: reproduce failure, isolate the failing step, summarize evidence, and stop before code edits.
Fix-now (simple path): If the user explicitly asks for a direct fix and one path is clearly the safest, say which path you are taking and implement without a second confirmation round. No flow tracking.
Option-first (complex path): present 2-3 repair options with flow tracking and wait for user selection.
Handoff: route runtime application bugs to
```
bug-fix
```
and security review requests to
```
security-review
```
.

</execution_modes>

<investigation_strategy>

如果

.hypercore/deploy-fix/flow.json

已存在，先读取该文件，从最后未完成的阶段（

in_progress

或

pending

）继续。不要重新启动已完成的阶段。

</flow_tracking>

<execution_modes>

明确使用以下分支之一：

仅诊断：复现故障、隔离失败步骤、总结证据，在代码编辑前停止。
立即修复（简单路径）：如果用户明确要求直接修复且存在明显最安全的路径，说明将采用的路径并直接实施，无需二次确认。无需流程跟踪。
先提供方案（复杂路径）：提供2-3种修复方案并进行流程跟踪，等待用户选择。
移交：将应用运行时bug转至
```
bug-fix
```
，将安全审查请求转至
```
security-review
```
。

</execution_modes>

<investigation_strategy>

Investigation Strategy

调查策略

Check these areas in order of likelihood:

Build logs: read the exact error output, identify the first failure point
Dependency issues: lockfile conflicts (
```
package-lock.json
```
/
```
pnpm-lock.yaml
```
integrity), missing packages, version mismatches, peer dependency warnings, hoisting problems

Config files:

tsconfig.json

package.json

next.config.*

vercel.json

vercel.ts

, CI workflow files, bundler config

Environment: Node.js version, env vars, platform-specific differences (local vs CI vs deploy target), memory limits (OOM during build)
Build cache: stale or corrupted build cache (
```
.next/
```
,
```
.turbo/
```
,
```
node_modules/.cache/
```
),
```
--force
```
rebuild to isolate
Cross-workspace: monorepo dependency graph, build order, shared package version drift
Recent changes:
```
git log
```
and
```
git diff
```
to find suspect commits that may have introduced the failure

</investigation_strategy>

按可能性顺序检查以下领域：

构建日志：读取确切的错误输出，确定第一个失败点
依赖问题：锁文件冲突（
```
package-lock.json
```
/
```
pnpm-lock.yaml
```
完整性）、缺失包、版本不匹配、对等依赖警告、依赖提升问题
配置文件：
```
tsconfig.json
```
、
```
package.json
```
、
```
next.config.*
```
、
```
vercel.json
```
/
```
vercel.ts
```
、CI工作流文件、打包器配置
环境：Node.js版本、环境变量、平台特定差异（本地 vs CI vs 部署目标）、内存限制（构建期间内存不足）
构建缓存：过期或损坏的构建缓存（
```
.next/
```
、
```
.turbo/
```
、
```
node_modules/.cache/
```
），使用
```
--force
```
重新构建以隔离问题
跨工作区：单体仓库依赖图、构建顺序、共享包版本漂移
最近变更：
```
git log
```
和
```
git diff
```
查找可能引入故障的可疑提交

</investigation_strategy>

Simple Path (Fix-now)

简单路径（立即修复）

Step	Task	Tool
1	Validate input, sequential-thinking (3 thoughts)	sequential-thinking
2	Classify as simple	-
3	Reproduce failure locally, read error output	Bash + Read
4	Identify root cause from logs/config	Read/Grep/Glob
5	Announce fix path and implement	Edit
6	Run validation (build/lint/typecheck/deploy)	Bash
7	Report outcome and changed files	-

步骤	任务	工具
1	验证输入，执行顺序思考（3步）	sequential-thinking
2	归类为简单	-
3	本地复现故障，读取错误输出	Bash + Read
4	从日志/配置中确定根本原因	Read/Grep/Glob
5	宣布修复路径并实施	Edit
6	运行验证（构建/lint/类型检查/部署）	Bash
7	报告结果及修改的文件	-

Complex Path (Option-first)

复杂路径（先提供方案）

Step	Task	Tool
1	Validate input, sequential-thinking (7+ thoughts)	sequential-thinking
2	Classify as complex, create `.hypercore/deploy-fix/flow.json`	Write
3	Deep investigation: reproduce, analyze logs, trace dependency chain -> update flow `investigate: completed`	Bash + Read/Grep/Glob + Edit
4	Present 2-3 fix options -> update flow `options: completed`	Edit
5	Wait for user selection -> update flow `confirm: completed`	Edit
6	Implement selected option -> update flow `fix: completed`	Edit/Write
7	Run validation -> update flow `verify: completed`	Bash + Edit
8	Report outcome, set flow status to `completed`	Edit

</workflow>

<option_presentation>

Use this format (complex path):

markdown

undefined

步骤	任务	工具
1	验证输入，执行顺序思考（7+步）	sequential-thinking
2	归类为复杂，创建 `.hypercore/deploy-fix/flow.json`	Write
3	深入调查：复现、分析日志、追踪依赖链 -> 更新流程 `investigate: completed`	Bash + Read/Grep/Glob + Edit
4	提供2-3种修复方案 -> 更新流程 `options: completed`	Edit
5	等待用户选择 -> 更新流程 `confirm: completed`	Edit
6	实施选定方案 -> 更新流程 `fix: completed`	Edit/Write
7	运行验证 -> 更新流程 `verify: completed`	Bash + Edit
8	报告结果，将流程状态设置为 `completed`	Edit

</workflow>

<option_presentation>

使用以下格式（复杂路径）：

markdown

undefined

Deploy Failure Analysis

部署故障分析

Root cause: ... Failure scope: [repo-wide / workspace / CI step / deploy target] Complexity: complex

根本原因：... 故障范围：[全仓库 / 工作区 / CI步骤 / 部署目标] 复杂度：复杂

Option 1: ... (Recommended)

方案1：...（推荐）

Pros:
Cons:
Risk:
Files:

优点：
缺点：
风险：
涉及文件：

Option 2: ...

方案2：...

Pros:
Cons:
Risk:
Files:

优点：
缺点：
风险：
涉及文件：

Option 3: ... (Temporary)

方案3：...（临时）

Pros:
Cons:
Risk:
Files:

Recommendation: Option N (reason ...) Which option should I apply? (1/2/3)


</option_presentation>

<implementation_rules>

- Do not modify code before user option selection unless in the explicit Fix-now branch.
- Avoid speculative edits; use evidence from build/CI/deploy logs only.
- Keep scope limited to the failing build/CI/deploy path and its direct dependencies.
- Always run targeted validation for the changed path: rebuild the failing target, re-run the failing CI step, or re-trigger the failing deploy.
- Report the commands run, the key result lines, and the touched files in the final report.
- If validation cannot run locally (e.g., CI-only environment), say why and what remains unverified.

优点：
缺点：
风险：
涉及文件：

推荐：方案N（原因...）应应用哪个方案？(1/2/3)


</option_presentation>

<implementation_rules>

- 除非在明确的立即修复分支中，否则在用户选择方案前不要修改代码。
- 避免推测性编辑；仅使用构建/CI/部署日志中的证据。
- 范围限制在失败的构建/CI/部署路径及其直接依赖。
- 始终对变更路径进行针对性验证：重新构建失败目标、重新运行失败CI步骤或重新触发失败部署。
- 在最终报告中说明运行的命令、关键结果行以及修改的文件。
- 如果无法在本地运行验证（例如仅CI环境），说明原因以及未验证的内容。

Reporting

报告

After execution, report:

markdown

undefined

执行完成后，报告：

markdown

undefined

Done

完成

Failure: [original error / failing step] Root cause: [what was wrong] Fix applied: [which option or approach] Changes: [list of changed files] Validation: [what was verified and result]


For complex path: also update `.hypercore/deploy-fix/flow.json` status to `completed`.

</implementation_rules>

<validation>

Execution checklist:

- [ ] ARGUMENT validated
- [ ] sequential-thinking completed (depth matches complexity)
- [ ] Complexity classified (simple/complex)
- [ ] Flow JSON created and maintained (complex path only)
- [ ] Root-cause evidence collected from logs/config
- [ ] 2-3 options presented (complex path) or fix path announced (simple path)
- [ ] User choice confirmed (complex path)
- [ ] Build/CI/deploy validation executed
- [ ] Outcome + touched files reported
- [ ] Flow JSON finalized with `completed` status (complex path only)

Forbidden:

- [ ] Speculative fix without build/CI/deploy log evidence
- [ ] Immediate implementation without options (complex path)
- [ ] Implementation without explicit user choice (complex path)
- [ ] Completion claim without running the failing build/CI/deploy command
- [ ] Skipping flow JSON updates in complex path

</validation>

故障：[原始错误 / 失败步骤] 根本原因：[问题所在] 应用的修复：[采用的方案或方法] 变更：[修改的文件列表] 验证：[验证内容及结果]


对于复杂路径：还需将`.hypercore/deploy-fix/flow.json`的状态更新为`completed`。

</implementation_rules>

<validation>

执行检查清单：

- [ ] ARGUMENT已验证
- [ ] 已完成顺序思考（深度匹配复杂度）
- [ ] 已完成复杂度分类（简单/复杂）
- [ ] 已创建并维护流程JSON（仅复杂路径）
- [ ] 已从日志/配置中收集根本原因证据
- [ ] 已提供2-3种方案（复杂路径）或宣布修复路径（简单路径）
- [ ] 用户选择已确认（复杂路径）
- [ ] 已执行构建/CI/部署验证
- [ ] 已报告结果及修改的文件
- [ ] 流程JSON已最终设置为`completed`状态（仅复杂路径）

禁止操作：

- [ ] 无构建/CI/部署日志证据的推测性修复
- [ ] 复杂路径下直接实施修复而不提供方案
- [ ] 复杂路径下未获得用户明确选择就实施修复
- [ ] 未运行失败的构建/CI/部署命令就声称完成
- [ ] 复杂路径下跳过流程JSON更新

</validation>