| name | debug-pipeline |
| kstack | true |
| description | Debug pipeline: investigate (prod or local) → fix-issues → scoped polish (deslop + code-simplify) → pattern-check → kestral-sync retroactive capture. Only invoked by the kstack subagent. |
| disable-model-invocation | true |
Debug Pipeline
You are investigating a reported problem, fixing the root cause, and capturing the outcome. Execute five steps in
sequence. Keep fixes minimal and targeted — this is not a feature build or a full review pass.
Mode selection: Pick the investigation mode before starting:
- prod — the issue is in production: user reports, error alerts, Cloud Run/Sentry signals, "users are seeing X".
- local — the issue is local: dev errors, test failures, build breaks, "I'm hitting Y locally".
- Auto-detect — mentions of "production", "users", "Cloud Run", "Sentry", or deployed behavior → prod. Otherwise
default to local. Ask via AskQuestion if genuinely ambiguous.
Start by creating a todolist with one item per step below. Each item's first sub-action is reading that step's
SKILL.md via the Read tool. Mark an item in_progress only after the Read tool call succeeds.
Step 1: Investigate
prod mode — work from deployed evidence, not assumptions:
- Gather the symptom, error message, affected users or endpoints, and time window. Check recent deploys.
- Identify whether the failure is in the service or a background job.
- Pull logs for that window, starting narrow (±2 min) and widening as needed.
- Correlate against recent code changes (
git log) and deployment history.
local mode — reproduce before theorizing: trigger the error, read the failing code path, and form a hypothesis. If
the project keeps a catalog of known bug classes, check it for a match first.
See context.md for the project's log/error-tracking tooling and any debugging catalog.
End this step with a root cause hypothesis backed by evidence (logs, stack traces, failing queries, code paths).
Present it to the user before fixing — if the evidence is inconclusive, say so and keep digging rather than guessing.
Step 2: Fix
Read .agents/skills/fix-issues/SKILL.md in full and follow its workflow. Treat the confirmed root cause as the issue
list. Apply the smallest safe fix, run lint/typecheck on touched files.
Step 3: Scoped polish
Run a lightweight polish pass scoped to the files touched by the fix only — not the full branch diff:
- Read
.agents/skills/deslop/SKILL.md — strip slop from the fix.
- Read
.agents/skills/code-simplify/SKILL.md — simplify the fix if warranted.
Do not run the full review-pipeline; debug fixes should stay small and targeted.
Step 4: Pattern check
Read .agents/skills/pattern-check/SKILL.md in full and follow its workflow. Search task history for prior occurrences
of this issue class. If 3+ matches are found, recommend .agents/skills/rule-evolution/SKILL.md to the user.
Skip this step if the task tracker is unavailable (auth check fails) — note the skip in the final summary.
Step 5: Task tracker sync
Post a structured bugfix record to the task tracker (see context.md for project-specific sync method):
- If no active tracking task matches this bug, create a new bugfix task
- If an active tracking task already exists, post a bugfix comment (root cause, fix, evidence links)
- Link the branch/PR to the tracking task
- Set status:
awaiting_review while PR is open; done only on merge
Skip only if the task tracker is unavailable and the user doesn't specify a task.
Final Output
After all steps, present a final summary:
- Root cause and the evidence that confirmed it
- Fix applied (files touched, what changed)
- Pattern check verdict (one-off / cluster / confirmed pattern — and whether rule-evolution was recommended)
- Kestral task created/updated (or skipped)
- Any remaining risks or follow-ups (rollback considerations, monitoring to watch)
Rules
- Follow the project's coding rules in
.cursor/rules/ (read engineering-principles.mdc and meta-workflow.mdc).
- Never apply a fix before presenting the root cause hypothesis with evidence.
- Run lint and typecheck after making changes (see context.md for exact commands).
- Use the AskQuestion tool to resolve ambiguity rather than guessing.
Project Context
Read context.md and apply it as additional project-specific constraints layered on top of this
workflow. If it does not exist, skip this section.
