whisper-shortcut

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.

Review the app's LLM architecture and interaction design against current provider best practices (OpenAI, Gemini, xAI), then deliver a prioritized "keep / change / later" roadmap with concrete implementation slices.

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.

View application logs via the project's bash script. Use when debugging issues, investigating errors, or when the user asks to check or show logs. Logs are the primary way to see what the app is doing.

Applies official Google best practices when writing or editing Gemini system prompts (systemInstruction). Use when creating or changing system prompts for Gemini (e.g. transcription, Dictate Prompt, Prompt & Read), when reviewing prompt text in AppConstants or SpeechService, or when the user asks about Gemini prompt design.

When the user wants to push, commit, or "save to git", first rebuild the app and only proceed with commit and push if the build succeeds. Use when the user says push, commit and push, or deploy changes to git.