| name | harness-diagnose |
| description | Disciplined diagnosis workflow for failing gates, regressions, flaky behavior, performance regressions, and suspicious backend/runtime behavior. Use when the user reports a bug, broken invariant, failing command, failing test, or asks to diagnose/debug a problem.
|
Harness Diagnose
Use this skill for bugs and regressions.
Workflow skills guide process. Ownership skills still decide writable boundaries.
Phases
- Build a feedback loop.
- Reproduce the exact symptom.
- Generate 3-5 ranked falsifiable hypotheses.
- Instrument one boundary or variable at a time.
- Fix the smallest causal closed loop.
- Add regression evidence at the same semantic level.
- Run path-scoped gates from
agent/manifests/gate-matrix.yml.
- Report evidence and residual uncertainty.
Feedback Loop Options
Prefer fast, deterministic, agent-runnable signals:
- failing unit, service, integration, replay, or contract test
- validator or gate command
- CLI invocation with fixture input and expected output
- HTTP request against a running server
- replayed event, outbox, or projector trace
- throwaway harness isolated to one service, server, worker, or repo-tool path
- stress loop for flakes or concurrency issues
If no credible loop can be built, stop and state what was tried and what artifact is needed.
Instrumentation Rules
- Every probe must test one hypothesis.
- Prefer debugger, targeted assertion, or narrow logs over broad logging.
- Tag temporary logs with a unique prefix and remove them before completion.
- For performance regressions, measure first and fix second.
Completion Report
State:
- violated invariant
- causal boundary: contract, service, server, worker, platform, tooling, docs, or cross-boundary
- repair made
- regression evidence added or why no correct seam exists
- gates run
- gates not run
- residual risk or uncertainty
