Run any Skill in Manus with one click

debugging-workflow

Stars65

Forks8

UpdatedMay 30, 2026 at 07:14

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.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

mgsgde

mgsgde/whisper-shortcut

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

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.

Debugging Workflow

Rule

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).

1. Instrumentation (how to add logs)

Log function entry/exit, parameters, return values, state changes. Use structured messages.
Categories (choose the right one):

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)")

2. Full debug flow (when finding a bug)

Add instrumentation (see above) so the relevant path is visible in logs.
Rebuild: bash scripts/rebuild-and-restart.sh
Give the developer a short plan: numbered steps to reproduce (e.g. "1. Start app, 2. Trigger Speech-to-Prompt with shortcut X, 3. Say Y, 4. Wait for processing"). Ask them to do it and say when done.
After they reproduced: use view-logs-via-bash (bash scripts/logs.sh -t 5m or -f 'PROMPT-MODE'), analyze logs, summarize findings and suggest fix or next step.

3. Hangs / unresponsive UI / 100% CPU (different from a logic bug)

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:

Confirm + locate: pgrep -x WhisperShortcut, then ps -p <pid> -o %cpu,state. A hung app is state R at ~100% CPU (idle is S at ~0%).
Capture the stuck stack: 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.
Correlate the last log timestamp with the trigger (what was just rendered or inserted), then add DebugLogger tripwires around that step so the next occurrence is unambiguous in the log.
The app won't self-recover — kill -9 <pid> before rebuilding.

When to apply

Bug report / "it doesn't work" / "debug" / "figure out why" → full flow (instrument → rebuild → repro → logs).
App froze / beachball / spinning / unresponsive / pinned CPU → section 3 (sample the process first).
"Add logging" / "see what's happening" → instrumentation only (optionally rebuild).
"View existing logs" only → use view-logs-via-bash instead; skip for pure feature work with no bug or visibility request.

More from this repository

same repository

analyze-chat-freeze

mgsgde/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.

2026-07-0565

run-whisper-shortcut

mgsgde/whisper-shortcut

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.

2026-06-2965

analyze-user-interactions

mgsgde/whisper-shortcut

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?".

2026-06-2965

validate-audio-verification

mgsgde/whisper-shortcut

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.

2026-06-2965

audit-llm-context

mgsgde/whisper-shortcut

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".

2026-06-0565

llm-model-docs

mgsgde/whisper-shortcut

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.

2026-06-0565

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.

Debugging Workflow

Rule

1. Instrumentation (how to add logs)

Log function entry/exit, parameters, return values, state changes. Use structured messages.
Categories (choose the right one):

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)")

2. Full debug flow (when finding a bug)

Add instrumentation (see above) so the relevant path is visible in logs.
Rebuild: bash scripts/rebuild-and-restart.sh
Give the developer a short plan: numbered steps to reproduce (e.g. "1. Start app, 2. Trigger Speech-to-Prompt with shortcut X, 3. Say Y, 4. Wait for processing"). Ask them to do it and say when done.
After they reproduced: use view-logs-via-bash (bash scripts/logs.sh -t 5m or -f 'PROMPT-MODE'), analyze logs, summarize findings and suggest fix or next step.

3. Hangs / unresponsive UI / 100% CPU (different from a logic bug)

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:

Confirm + locate: pgrep -x WhisperShortcut, then ps -p <pid> -o %cpu,state. A hung app is state R at ~100% CPU (idle is S at ~0%).
Capture the stuck stack: 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.
Correlate the last log timestamp with the trigger (what was just rendered or inserted), then add DebugLogger tripwires around that step so the next occurrence is unambiguous in the log.
The app won't self-recover — kill -9 <pid> before rebuilding.

When to apply

Bug report / "it doesn't work" / "debug" / "figure out why" → full flow (instrument → rebuild → repro → logs).
App froze / beachball / spinning / unresponsive / pinned CPU → section 3 (sample the process first).
"Add logging" / "see what's happening" → instrumentation only (optionally rebuild).
"View existing logs" only → use view-logs-via-bash instead; skip for pure feature work with no bug or visibility request.