From spacelift
This skill should be used when the user wants to debug a failed Spacelift run, understand why a plan or apply failed, or investigate Spacelift errors. Follows a structured workflow: identify the failed run, fetch history and logs, parse errors, and present findings with fix suggestions. Activates on: "why did spacelift fail", "spacelift plan failed", "spacelift error", "debug spacelift", "spacelift apply failed", "spacelift failure", "fix spacelift", "what went wrong spacelift", "spacelift broken", "perché spacelift ha fallito", "errore spacelift", "spacelift rotto", "debug spacelift", "correggi spacelift".
npx claudepluginhub fabn/claude-plugins --plugin spaceliftThis skill uses the workspace's default tool permissions.
Debug failed Spacelift runs: identify the failure, fetch logs, parse Terraform errors, and suggest fixes.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Debug failed Spacelift runs: identify the failure, fetch logs, parse Terraform errors, and suggest fixes.
Reference files: Consult reference/spacectl-tools.md for the full MCP tool catalog and CLI equivalents.
spacelift.spacectl-mcp): list_stack_proposed_runs, list_stack_runs, get_stack_run, get_stack_run_logs, get_stack_run_changesUse ToolSearch with query spacelift to check if MCP tools are available. See reference/spacectl-tools.md § Tool Detection.
Try these approaches in order:
git branch --show-currentlist_stack_proposed_runs for the stack, filter by branchUse get_stack_run (MCP) to see the run's current state and metadata.
For phase-level history (which phase failed and when), use the GraphQL query:
spacectl api '
query {
stack(id: "<stack-slug>") {
run(id: "<run-id>") {
state
history { state timestamp note }
}
}
}'
The history array shows state transitions. Look for the last state before FAILED — this tells you which phase failed (PLANNING, APPLYING, INITIALIZING, etc.).
Use get_stack_run_logs (MCP) with stack_id and run_id.
Strategy for large logs:
skip: 500, limit: 200) — errors are usually near the endError: lines (main error message)on <file> line <N>: (location)resource "<type>" "<name>" (affected resource)│ bordered blocks (Terraform diagnostic output)For phase-specific logs via CLI GraphQL:
spacectl api '
query {
stack(id: "<stack-slug>") {
run(id: "<run-id>") {
logs(state: PLANNING) {
messages { message timestamp }
}
}
}
}'
Use get_stack_run_changes (MCP) to see what resources were being modified when the failure occurred.
Structure the output as:
## Failed Run Analysis
**Stack**: `<stack-slug>`
**Run**: `<run-id>`
**Failed Phase**: PLANNING / APPLYING / INITIALIZING
**Failed At**: <timestamp>
### Error
<extracted error message, clean of ANSI codes>
### Affected Resources
<table of resources being changed>
### Suggested Fix
<analysis of the error with actionable suggestions>
Common error categories and suggestions:
| Error Pattern | Likely Cause | Suggestion |
|---|---|---|
Error: Reference to undeclared resource | Resource renamed/removed | Check resource references in the module |
Error: Invalid provider configuration | Missing or wrong provider config | Verify provider block and credentials |
Error: Error acquiring the state lock | Concurrent run or stale lock | Wait or force-unlock if stale |
Error: Unsupported attribute | Provider version mismatch | Check provider version constraints |
Error: Error creating/updating <resource> | AWS/cloud API error | Check IAM permissions and resource limits |
exit status 1 with no Terraform error | Init or hook failure | Check INITIALIZING phase logs |
| Situation | Action |
|---|---|
| MCP tools not available | Fall back to CLI. See reference/spacectl-tools.md § CLI Equivalents |
| No FAILED runs found | Confirm with user — maybe the run is still in progress or succeeded |
| Logs are empty | Try fetching with different skip/limit, or use GraphQL for phase-specific logs |
| Error is in INITIALIZING phase | Check for .spacelift/ hooks, provider init issues, or backend config problems |
| Authentication failure | Check SPACELIFT_API_GITHUB_TOKEN and SPACELIFT_API_KEY_ENDPOINT env vars |
reference/spacectl-tools.md — Full MCP tool catalog, CLI equivalents, GraphQL queries