| name | deploy-fix |
| description | [Hyper] Diagnose and fix build failures, CI pipeline errors, and deployment errors across the entire repository or a specific folder. Routes simple build breaks directly; tracks complex multi-system failures via .hypercore/deploy-fix/ JSON flow. |
| compatibility | Use in environments with code exploration (Read/Grep/Glob), editing (Edit), and shell execution (Bash). |
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.
<output_language>
Default all user-facing deliverables, saved artifacts, reports, plans, generated docs, summaries, handoff notes, commit/message drafts, and validation notes to Korean, even when this canonical skill file is written in English.
Preserve source code identifiers, CLI commands, file paths, schema keys, JSON/YAML field names, API names, package names, proper nouns, and quoted source excerpts in their required or original language.
Use a different language only when the user explicitly requests it, an existing target artifact must stay in another language for consistency, or a machine-readable contract requires exact English tokens. If a localized template or reference exists (for example *.ko.md or *.ko.json), prefer it for user-facing artifacts.
</output_language>
<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.
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.
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>
<instruction_contract>
| Field | Contract |
|---|
| Intent | Diagnose and repair concrete build, CI, or deployment failures. |
| Trigger | Activate only when the user provides or asks to fix a build/CI/deploy failure surface. |
| Scope | Own failure classification, reproduction, log/config analysis, build/deploy-layer fixes, flow tracking for complex cases, and validation reporting. |
| Authority | User and project instructions outrank this skill; build logs, CI/deploy output, config files, and local validation are evidence. |
| Evidence | Collect exact failing command output, first failure point, relevant config, dependency state, and recent-change context before editing. |
| Tools | Use local reads, edits, Bash validation, and .hypercore/deploy-fix/flow.json for complex cases; external production side effects require explicit user authority. |
| Output | Korean failure/root-cause/fix/validation report, plus updated flow JSON when the complex path is used. |
| Verification | Re-run the failing build/CI/deploy command or the narrowest equivalent local check, then record commands and results. |
| Stop condition | Stop when the failure is fixed and verified, diagnose-only output is delivered, or a complex option/permission/production blocker is reported. |
</instruction_contract>
<argument_validation>
If ARGUMENT is missing, ask immediately:
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>
Mandatory Structured Reasoning
Before implementation, perform an internal structured reasoning pass. Depth scales with complexity:
- Simple (3 steps): Identify failing step -> determine fix -> verify approach
- Medium (5 steps): Classify -> reproduce locally -> hypothesize -> compare options -> recommend
- Complex (7+ steps): 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>
Complexity Classification
Classify immediately after the structured reasoning pass:
| 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>
Flow Tracking (Complex Path Only)
When classified as complex, initialize the flow:
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.
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 |
Resume support
If .hypercore/deploy-fix/flow.json already exists, read it first and continue from the last incomplete phase (in_progress or 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>
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>
Simple Path (Fix-now)
| Step | Task | Tool |
|---|
| 1 | Validate input, structured reasoning pass (3 steps) | internal reasoning |
| 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 | - |
Complex Path (Option-first)
| Step | Task | Tool |
|---|
| 1 | Validate input, structured reasoning pass (7+ steps) | internal reasoning |
| 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 |
<option_presentation>
Use this format (complex path):
## Deploy Failure Analysis
**Root cause**: ...
**Failure scope**: [repo-wide / workspace / CI step / deploy target]
**Complexity**: complex
### Option 1: ... (Recommended)
- **Pros**:
- **Cons**:
- **Risk**:
- **Files**:
### Option 2: ...
- **Pros**:
- **Cons**:
- **Risk**:
- **Files**:
### Option 3: ... (Temporary)
- **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.
Reporting
After execution, report:
## 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>
Execution checklist:
Forbidden:
