diagnosing-bugs
Diagnose hard bugs and performance regressions with reproducible evidence, focused hypotheses, and proportional instrumentation. Use when something is broken, failing, throwing, intermittently wrong, or unexpectedly slow.
- License 许可
- MIT
- 所属仓库
- stevesolun/ctx
- 最近更新
- 2026-10-15
- Stars
- ★ 593
- Forks
- 69
01 前言 Front Matter
- name
- diagnosing-bugs
- description
- Diagnose hard bugs and performance regressions with reproducible evidence, focused hypotheses, and proportional instrumentation. Use when something is broken, failing, throwing, intermittently wrong, or unexpectedly slow.
02 资源文件 3
- 参考文档agents/openai.yaml103 B
- 参考文档references/debugging-playbook.md2.3 KB
- 脚本scripts/hitl-loop.template.sh1.1 KB
03 SKILL.md 正文
Diagnosing Bugs
Start from evidence and adapt the depth of the investigation to the problem. Read relevant repository context and architectural decisions when they exist.
Establish a useful signal
Reproduce the reported symptom with the cheapest signal that distinguishes broken from fixed. A focused test or script is ideal when practical; logs, traces, snapshots, comparisons, or measured timings may be better for other failures. Tighten the loop by improving speed, specificity, and determinism.
If an exact reproduction is unavailable, continue with the strongest evidence available and state the limitation. Request an artifact, access, or temporary instrumentation only when it would materially improve the diagnosis.
For feedback-loop options and debugging tactics, load the
debugging playbook as needed. For a rare
manual reproduction, adapt
scripts/hitl-loop.template.sh.
Narrow and explain
Minimize the reproducing scenario when doing so will shrink the search space. Form a small ranked set of falsifiable hypotheses from the evidence, then choose probes that best distinguish them. Share hypotheses with the user when their domain knowledge could redirect the investigation; do not make routine progress depend on a checkpoint.
Use targeted instrumentation at boundaries that separate plausible causes. Change as little as practical per probe. For performance regressions, establish a baseline and use profiling, query plans, or bisection before optimizing.
Fix and verify
Add a regression test when a stable seam can represent the real failure. If it cannot, explain the coverage gap rather than adding a misleading test. Apply the smallest justified fix, then rerun both the focused signal and relevant nearby checks.
Remove temporary instrumentation and artifacts unless the user wants to retain them. Report the observed cause, the evidence that supports it, what was verified, and any remaining uncertainty. Recommend architectural follow-up only when the diagnosis exposes a concrete recurring weakness.
04 同仓库更多 Skills
toolbox
Pre/post dev toolbox — named bundles of skills/agents loaded before development work and councils of experts invoked after. Run /toolbox or the toolbox.py CLI to list, activate, initialize, export, import, and validate toolboxes. Invoke at the start or end of a dev session, when setting up a new repo, or when sharing toolboxes with a team.
skill-router
Alive skill router — reads the current project's stack and loads/unloads skills dynamically. Invoke at session start or when project context changes.
repo-stats-autoupdate
Keeps README badge + inline counts in sync with the real number of skills, agents, graph nodes/edges, communities, converted pipelines, and test inventory. Runs automatically on every commit via a git pre-commit hook. Use when the README drifts from reality or before publishing a release.
find-skills
Discover installable agent skills from ctx's shipped Skills.sh catalog, the Skills.sh search API, and the npx skills CLI. Use when a user asks whether a skill exists, wants to add/update a skill, or needs a repeatable procedure for finding candidate skills safely.
no-mistakes
Validate committed feature-branch changes through the no-mistakes pipeline: intent, rebase, review, test, docs, lint, push, PR, and CI. Use when the user asks to run no-mistakes, ship safely, validate before pushing, or gate a change before it reaches upstream.
zoom-out
Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.