ha-debug
Hope-native debugging for code failures, regressions, crashes, flaky behavior, and bad output: reproduce or characterize, rank falsifiable hypotheses, fix the smallest root cause, and prove the failing path.
git clone --depth 1 https://github.com/shiwenwen/hope-agent /tmp/ha-debug && cp -r /tmp/ha-debug/skills/ha-debug ~/.claude/skills/ha-debugSKILL.md
# Hope Debug Debug from evidence, not from the first plausible explanation. This is a decision process, not a mandatory four-stage ceremony. ## 1. Characterize The Failure Capture the strongest available evidence: - Exact symptom, expected behavior, and observed behavior. - Reproduction steps, failing command, stack trace, log range, or persisted state. - Whether it is deterministic, intermittent, platform-specific, data-specific, or timing-sensitive. - Recent relevant diffs, dependency/config changes, and known-good boundary. If reproduction is unsafe or requires unavailable credentials, characterize it from logs, fixtures, state, and code paths. State the evidence gap explicitly. ## 2. Bound The Fault Trace the smallest credible path through inputs, state transitions, persistence, concurrency boundaries, and outputs. For multi-component systems, compare what crosses each boundary rather than adding broad instrumentation everywhere. Common high-value checks: - Stale or duplicated persisted state. - Error swallowing, fallback, retry, cancellation, and timeout paths. - Async ordering, locks, process boundaries, and late results. - Platform, locale, permission, path, and environment assumptions. - Mismatch between source-of-truth data and UI projection. ## 3. Rank Falsifiable Hypotheses Keep one or two active hypotheses. For each, write: - Why it explains the evidence. - What observation would disprove it. - The cheapest discriminating check. Run the discriminating check before editing when practical. If a tiny, obvious fix is itself the cheapest safe experiment, keep it reversible and inspect the result before broadening scope. ## 4. Fix The Root Cause - Patch the smallest ownership boundary that restores the contract. - Avoid subsystem rewrites before the fault is proven. - Preserve unrelated user work and existing public behavior. - Add defense-in-depth only when it covers a demonstrated adjacent failure, not as speculative cleanup. After two failed fix attempts, stop patching variants. Re-read the original evidence, challenge the shared assumption, and narrow the boundary again. ## 5. Prove The Failing Path Use `ha-test-strategy` to choose the regression form and `ha-verify` to confirm completion. Prefer a check that would have failed before the fix: - Focused automated regression test. - Existing failing command or deterministic fixture. - Before/after database or log query. - Manual reproduction when automation is not credible. Passing compilation alone does not prove a runtime bug fixed. If the real path cannot be exercised, report the strongest substitute and remaining uncertainty. ## Stop Conditions Pause and ask for input only when progress requires inaccessible user state, an external system change, destructive action, or a product decision. Do not invent data or mark an unreproduced hypothesis as confirmed. ## Smoke Prompts - "This test fails intermittently; find and fix the root cause." - "The UI shows stale state after restart; diagnose the persistence path." - "Use this session id and logs to explain the regression, then repair it."
>
Use when the user asks to draft, polish, translate, or reply to an email. Produces a clean draft with subject line, greeting, body, and sign-off, plus a pre-send self-check.
Use when the user mentions 飞书 / Feishu / Lark workspace operations: docx (云文档) read/write, bitable (多维表格) records / views / dashboards, drive (云盘) upload/download, wiki (知识库) link resolution, approval (审批) instance create/cancel/query, calendar (日历) event create/list/update + attendees, contact (联系人) user/department lookup, hire (招聘) job/talent/application listing. Trigger on phrases like 'OKR 周报', '把这份文档发到飞书云盘', '给团队拉个评审会议', '查 [姓名] 的联系方式', '撤销那条审批', '/wiki 链接', or any request that mentions a feishu / lark URL / token (doxcn.../bascn.../wikcn.../boxcn.../om_...).
Hope Agent browser automation — the standard `status → tabs → snapshot → act` loop, stale-ref recovery rules, and what to do when login / 2FA / captcha / camera-prompt / dialog blocks progress. Load this skill whenever you reach for the `browser` tool. Trigger on: user asks the agent to open / control / click / scrape / log into / verify something in a web app ('open X and click Y', '打开 X 然后点击 Y', 'log into my Gmail', 'scrape this page', 'fill out the form on X'); user reports a flow that requires real browser context (cookies, JS-rendered content, OAuth).
Discover and install third-party skills from external registries when the user needs a capability that no currently-active skill covers. Trigger when: (1) the user explicitly asks 'find a skill for X', 'is there a skill that does X', 'install a skill to X', (2) the user requests a well-known integration (Slack, Notion, Trello, GitHub, Hue, Sonos, iMessage, weather, TTS, transcription …) that isn't in the active skill catalog, (3) you are about to hand-write ad-hoc shell / API code for a domain that almost certainly has a published skill. Do NOT trigger if an active skill already covers the need — scan the visible skill catalog first.
Self-service diagnostics — query Hope Agent's local SQLite databases (logs / sessions / background jobs) directly via the `exec` tool to investigate problems, analyze usage, and locate root causes. Trigger on: user reports something broken / failing / slow / stuck / not responding ('X 不工作', 'X 报错', 'X 卡住', '为什么 X 失败', 'why did X fail', 'show me the logs', 'check what happened'); ad-hoc data analysis ('this week's token usage', '最近调用最多的工具', 'how many subagent runs failed', 'tool error rate', 'find sessions where X happened'); verifying a fix ('did the error stop after I changed Y'). Use BEFORE asking the user to paste log snippets — the data is on disk, query it directly. Read-only — SELECT only, never UPDATE/DELETE/INSERT/DROP.
Hope Agent native macOS desktop control — the standard `mac_control` status / diagnostics / apps / dock / spaces / snapshot / visual / windows / menu / clipboard / dialog loop, target-first action rules, no-blind-coordinate policy, and recovery for stale AX/window/menu/dialog state. Load whenever using `mac_control`, or when the user asks to control local Mac apps, Dock, Spaces, click/type/menu/window/dialog/clipboard, automate Finder/TextEdit/System Settings, visually locate UI, or says 控制 Mac, macOS 自动化, 点按钮, 打开应用, Dock, Space, 关闭窗口, 菜单点击, 视觉定位.
Self-understanding and issue reporting for Hope Agent itself. Use when the user asks how Hope Agent works internally, asks about its own source code/docs/runtime behavior, reports a bug/failure/slowness/crash, asks to diagnose logs, or asks to create/submit a GitHub issue for a bug, feature request, or improvement (including when there is no bug). Chinese triggers: 自查, 了解自己, 自我诊断, 排查 Hope Agent, 提交 issue, 需求 issue, 功能改进.