IssueOps Debugging

Activation and Scope

Reproduce bugs, test failures, and regressions; isolate and verify their root cause before applying the smallest fix. You are a diagnostician, not a refactoring or restructuring agent. The method applies across languages, OSes, and stacks. Never diagnose from memory or symptoms alone. If the reproduction command is physically unavailable, record the blocker and label any hypothesis unconfirmed.

This body is the complete actor contract. Optional examples are not prerequisites; a copied skill needs neither sibling skills nor evaluator material. Resolve local references from the real, symlink-resolved skill directory, not the target cwd.

IssueOps Benchmark Artifact Contract

When contributing to an IssueOps artifact or benchmark response, include:

Reproduction: <exact command/input, exit code, repeatability>
Failure signature: <stable error line, stack frame, diff, or trace divergence>
Root cause hypothesis: <falsifiable cause statement>
Isolation: <bisect, trace diff, divide-and-conquer, or direct line proof>
Minimal fix boundary: <smallest file/function/behavior surface to change>
Known cautions: <matching .issueops/CAUTIONS.md or cautions/ entry path, or "none matched">
Verification: <rerun, regression test, or blocker if verification cannot run>

For trivial syntax/import/path failures, keep this short, retain the exact failure signature, and skip heavyweight diagnosis.

Method: Reproduce → Translate → Isolate → Hypothesize → Verify → Fix → Learn

1. Reproduce

Run the exact failing command yourself; preserve complete stdout, stderr, exit code, inputs, and a stable failure signature. Check repeatability: distinguish deterministic failures from intermittent ones, recording the pass/fail ratio for flaky behavior. If it will not reproduce, record attempts and ask for OS, versions, exact inputs, and environment before diagnosing.

When the repo has .issueops/TESTING.md, take the canonical test command and flags from it so the reproduction matches what the repo's verification runs.

Before forming any hypothesis, read .issueops/CAUTIONS.md (index and the module for the failing area) and search dated .issueops/cautions/ records for the failure signature. A recorded pitfall that matches is the first hypothesis; record its path under Known cautions, or record "none matched".

2. Translate

Use the available IssueOps lint_diagnose surface for a first-pass hypothesis:

issueops project lint-diagnose --json -- go test ./pkg/auth -run TestLoginFlow -count=1

The MCP form takes structured command_argv, for example ["go", "test", "./pkg/auth", "-run", "TestLoginFlow", "-count=1"]. Use the target stack's command. Treat the returned cause, suggested fix location, and verification command as hypotheses, never as confirmed diagnoses.

Skip translation for an obvious syntax/import error, an unavailable runtime or IssueOps CLI/MCP surface, or a snapshot mismatch (use strategy D). Never send secrets or credentials; redact before any LLM call, or skip it. Missing IssueOps tools do not block direct isolation.

3. Isolate

Four Strategies

Choose by failure shape; preserve user changes during diagnostic experiments.

A. Regression / bisect. Identify known-good and known-bad commits and a test that exits 0 for good and nonzero for bad. Bisect between them, classify each revision with that test, then inspect the breaking commit's diff. Save the initial revision and return to it when done; do not overwrite dirty work. If available, git-operations can supply its bisect protocol and git log -S guidance, but is not required to identify the regression window.

B. Broad failure / divide and conquer. Temporarily disable half the suspected surface and rerun. Failure remaining implicates the enabled half; a passing run implicates the disabled half. Repeat until isolated to at most 20 lines. Restore only your diagnostic edits; a changed setup is not automatically proof of cause.

C. Intermittent failure / trace diff. Run the test 10 times and capture each trace. Separate passes and failures; locate their first divergence. When available:

issueops trace analyze --input /tmp/debugging-traces.jsonl --json

Retain failure_class, recurring_pattern, proposed_knob, overfit_risk, and verification_command from that analysis.

Strategy D: Snapshot/Golden Diff. Check git status --short -- PATH first; stop if the target is dirty. Regenerate the clean target with the test runner's update mode, read git --no-pager diff -- PATH, and restore only that QA-generated change after inspection. Do not overwrite user work. Treat timestamps, absolute paths, hostnames, working-tree-dependent listings, and ignored files in snapshots as non-hermetic inputs: fix those inputs, not merely the golden expectation.

Other first probes: connection/timeout → process list and port bindings; import/build failure → new imports in the diff; panic/null → stack frame; leak/performance regression → CPU/memory/allocation profiling. Assertion failures use divide and conquer and, if useful, translation. Know the target stack's test, debug logging, trace, profiling, variable-inspection, test-bisect, and race tools. For a stalled verification-progress surface, the self-verify-progress-heartbeat fixture is a concrete replay example; preserve its event-based observation rather than treating a silent terminal as proof of a hang.

4. Hypothesize

Before touching fix code, state a specific cause that one concrete test can disprove. Identify the suspected ordering, input, or boundary and the predicted result. Reject vague claims such as "auth is broken" or "the code looks wrong."

5. Verify the Hypothesis

Run the disproving test and record command, result, and what it establishes. If disproven, record what was learned and return to isolation. After five failed hypothesis cycles, stop and present a differential diagnosis ranked by likelihood; ask the user for guidance rather than continue guessing.

6. Fix and Verify

Only after confirmation, apply the smallest root-cause fix, never a symptom patch or adjacent refactor. If a fix would exceed 20 lines, return to isolation; this skill does not apply a >20-line fix for one cause. Architectural fixes require a planning handoff with the confirmed diagnosis, not an expanded debugging edit.

Rerun the original reproduction, run the existing full test suite, and add a targeted regression test that fails if this bug returns. Check related behavior. Record actual outcomes or the precise blocker; do not call an unrun check passed.

7. Learn

Record a durable Reflexion-style lesson: symptom, confirmed cause, minimal fix, verification, and next preventive action, especially for recurring patterns. When available, issueops self-augment lesson records the lesson; otherwise include it in the diagnosis for the owning workflow to retain. See the optional example for the existing command syntax; do not invent unavailable tools.

Stop Rules

• Confirmed cause, verified fix, and passing regression tests: DONE.
• Five unsuccessful hypothesis cycles: ranked differential diagnosis and guidance request.
• Cannot reproduce: attempt evidence and environment/input request, not a diagnosis.
• Architectural change required: deliver diagnosis for implementation planning.
• Production data/secrets involved: stop, do not access them, and surface the boundary.

IssueOps Integration (Only When a Cycle Exists)

1. Diagnose bugs during implement or feedback; preserve the lifecycle ID. Let issueops next --id "$ISSUEOPS_ID" --json identify the owning stage. Do not infer or advance phase from a debugging result; stop on blocked routing.
2. Deliver the labeled evidence to that stage for authenticated feedback recording (source issueops-debugging, root cause → fix → verification). The supported issueops feedback add and issueops status aliases are not authorization.
3. Before durable recording, the owner must match exact ID, generation, native actor, and canonical cwd against current state. Use issueops execution whoami --json's record_actor_flags for records and claim_actor_flags for lease operations; never hand-build flags or bypass a mismatch/another holder.
4. Plan-changing fixes require contract_change feedback and the owner's plan update/review before implementation. Keep its gate/artifact order, including failing evidence before the fix and verification before completion. A failure inside Verified Execution (after 2+ criterion failures) returns the diagnosis there for fix/channel QA rather than self-certifying that workflow.
5. Preserve the user's authorization and stop boundary. No implicit commit, push, publication, or cleanup; destructive cleanup needs a target/fingerprint preview and separate confirmation. Stage/lease state is not approval. Do not add another approval prompt for work already authorized. If the stage is unavailable, return findings with recording explicitly pending; standalone diagnosis continues.

External dependency bugs may use web research of trackers/changelogs; architectural changes may use implementation planning. These are optional collaborations, not installation requirements or permission to widen this task.

Optional Reference

Stack commands and worked examples contains language tables, bug-pattern illustrations, and an example lesson command.