菜单
Debugging in WhisperShortcut: add DebugLogger instrumentation (with right categories), rebuild, give developer a manual repro plan, then fetch and analyze logs. Use when the user reports a bug, asks to debug, wants logging added to understand flow, or the app hangs / freezes / pins the CPU.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Triage a WhisperShortcut chat-window main-thread freeze from the watchdog's on-disk hang captures and app logs — classify real vs. false-positive, localize the wedge, confirm whether the shipped fix held, and continue root-causing new variants. Use when the app beachballs/freezes/pins CPU during chat, when a new hang-*.txt appears, or when asked to investigate a chat hang.
Build, launch, drive, screenshot, and walk through the WhisperShortcut macOS menu-bar app from a user's perspective. Use when asked to run, start, launch, build, screenshot, test onboarding, cognitive walkthrough, first-run activation, or visually confirm UI changes in the real app (not just tests). Covers Welcome onboarding, status menu, Settings, and Chat.
Mine the local user-interaction JSONL logs for systematic failures and propose improvements across system prompts, defaults, code logic, logging, and UI. Use when the user asks for improvements based on actual usage — e.g. "what's going wrong in Dictate Prompt?", "analyze my recent interactions", "find patterns in the logs", "what should we improve based on how I'm using the app?".
Validate end-to-end that Smart Improvement audio verification is actually working — audio is captured for dictation, selected content-aware to verify recurring candidate terms, attached only when the asymmetry rule passes, used by the dictation and Whisper Glossary focuses, and retained across runs (pruned by age). Use when the user asks "is audio verification working?", after implementing or modifying the Smart Improvement audio verification feature, or when investigating why a glossary/dictation suggestion was or was not produced.
Systematically reviews all LLM-context files in this repo (.cursor/commands/, .cursor/rules/, .cursor/skills/) for stale references, factual drift vs the current codebase, redundancy across files, and files that no longer earn their slot. Produces a tiered report (broken / drift / dedup / hygiene). Use when the user asks to audit, review, check, or validate LLM-context files, cursor rules, claude skills, prompt files, or "are these instructions still correct".
Look up current official documentation AND current model lineups for OpenAI, Google Gemini, and xAI (Grok). Use BEFORE adding/changing model IDs, before answering model-capability questions (e.g. "does gpt-4o-transcribe accept a system prompt?"), AND proactively whenever you touch chat/transcription/TTS code paths (provider files, SettingsConfiguration, TranscriptionModels, ChatModelCommandResolver, SpeechService) — compare our current defaults to what each provider has shipped recently, and surface upgrade suggestions to the user if newer GA models exist. AI moves fast — always check live docs first.
| name | debugging-workflow |
| description | Debugging in WhisperShortcut: add DebugLogger instrumentation (with right categories), rebuild, give developer a manual repro plan, then fetch and analyze logs. Use when the user reports a bug, asks to debug, wants logging added to understand flow, or the app hangs / freezes / pins the CPU. |
Logging rule (DebugLogger only) is in .cursor/rules/index.mdc; this skill covers the instrument → rebuild → repro → analyze-logs flow. For "just add logging" do only the instrumentation (and optionally rebuild).
| Method | Use for |
|---|---|
logNetwork() | API calls, requests, responses |
logAudio() | Recording, playback, chunking |
logSpeech() | Transcription, prompt, TTS |
logError() | Errors and failures |
logDebug() or log() | Detailed flow / internals |
logInfo() | General info |
logWarning() | Warnings |
logUI() | UI / menu / window events |
logSuccess() | Successful completion |
Example:
DebugLogger.logSpeech("transcribe(start) url=\(audioURL.lastPathComponent)")
// ...
DebugLogger.logSpeech("transcribe(done) chars=\(result.count)")
DebugLogger.logError("API request failed: \(error.localizedDescription)")
bash scripts/rebuild-and-restart.shbash scripts/logs.sh -t 5m or -f 'PROMPT-MODE'), analyze logs, summarize findings and suggest fix or next step.When the app freezes (beachball, pinned CPU), the logs go silent at the freeze
point — the last line is where it wedged, and view-logs-via-bash alone can't
go further. Switch tools:
pgrep -x WhisperShortcut, then ps -p <pid> -o %cpu,state.
A hung app is state R at ~100% CPU (idle is S at ~0%).sample <pid> 3 -mayDie > /tmp/ws_hang.txt. Aggregate
the hot frames (grep -oE the repeated …Layout / …dylib symbols). All samples
inside one runloop-observer transaction with none in event-wait = a single
unbounded operation (e.g. a non-converging SwiftUI layout loop), not 60fps churn.DebugLogger tripwires around that step so the next
occurrence is unambiguous in the log.kill -9 <pid> before rebuilding.sample the process first).