OpenWhisper

Branch-discipline rule for OpenWhisper — every code change ships from a feature branch, never directly to `main`. Parallel work uses `git worktree`, never two branches inside the main checkout. READ before any `git commit`, `git push`, or `git checkout`; before responding to "let's start on X" / "tackle Y" / "begin work on Z". Pairs with a PreToolUse hook (`.claude/hooks/branch-discipline.sh`) that blocks `git commit` / `git push` / `git merge` on `main` or `master` — the hook is the mechanical guarantee; this skill explains the why and the worktree pattern.

READ before adding or changing any animation, transition, hover, press feedback, or motion-bearing interactive element in OpenWhisper. Triggers - pill HUD shape/state changes, record-button or icon press/hover, mount/unmount transitions, settings pane switches, hotkey activation feedback, model-load placeholders, success/celebration states, sidebar nav active states. Also fires when the user asks "should this animate?" or "make this feel more alive."

Architecture rule — every behavior ships through the public library API + the headless CLI before/while the UI consumes it. UI is the headful layer on top of headless surfaces, never the only place a feature exists. READ before opening a new `#[tauri::command]`, a React-only feature, a private helper inside `apps/tauri/`, or any pub fn in `core/`. Two binary gates inside — start gate ("does `cli/src/commands/` already have a placeholder for the parent task?") and finish gate ("does `grep -r TASK-N cli/` return anything?"). If the parent task has a CLI placeholder, the CLI surface is part of the deliverable; "code-complete + UI green" is not done. Pairs with `openwhisper-orchestration-in-rust` (where logic lives) and TASK-81 doctrine ("CLI feature surface = UI feature surface = library surface").

Dev-only state-simulation rule — every "park the app in state X for inspection" affordance ships inside the existing DevToolsPanel sheet (`apps/tauri/src/components/dev-tools-panel.tsx`), not as a new floating widget, button, or pane. READ before adding a dev-only override (pill-state picker, fake-crash trigger, simulated stats, "skip the model load" toggle, etc.) for a feature you're building. The trigger lives in the bottom-left of the sidebar; one trigger, one sheet, every dev affordance inside.

OpenWhisper's product values and cross-platform UX rules. READ before proposing features, settings, paywalls, activation/hotkey changes, or anything that affects how the app feels to a user. Pulls together the constraints that make OpenWhisper "the open alternative to Superwhisper" rather than just-another-dictation-app.

Use when writing an implementation plan for a project that uses Backlog.md (detect via `backlog/` dir or `backlog.config.yml` at repo root, or project CLAUDE.md references the `backlog` CLI). Produces both a design-doc markdown in backlog/docs/plans/ AND a Backlog.md subtask tree under the parent task. Backlog is the single source of truth: tasks own status/ACs/notes, attached docs (specs + plans) live in `backlog/docs/`. Adds Backlog enforcement: subtask-per-plan-task, status tracking, commit-ref appending, ID-mapping reviewer check.

Platform-specific behaviors and prior regressions in OpenWhisper's Tauri shell. READ before touching input handling (global hotkeys, keyboard hooks), focus management, audio capture, text injection, or any code that crosses the Rust/WebView boundary differently between Windows and macOS. Each entry below was earned by a real bug — not speculation.

UI work discipline rule — every UI change loads the `shadcn` skill first, and every settings/option control choice (slider vs select vs input vs toggle group) is researched against shadcn-canonical patterns before committing. READ before editing any file under `apps/tauri/src/components/` or `apps/tauri/src/lib/use-*.ts`, before adding a new control or settings row, before picking a UI primitive, or before reaching for a styled `<div>` instead of a shadcn component. Applies to React components, settings panes, hooks, layouts, slider/select/input/toggle decisions, and anything that changes what the user sees on screen.

Task close-out rule for OpenWhisper — code-complete + tests-green is NOT Done. READ before flipping a Backlog task (or claiming a feature is "done", "shipped", "complete") past In Review. Applies to TASK-N, TASK-N.M subtasks, PR descriptions, end-of-turn summaries, and follow-up scheduling pitches.

Write effective, context-efficient AI agent skills. Use when creating, editing, refactoring, or reviewing a skill — including discipline-enforcing skills (TDD-style, verification gates, "do X before Y") that must resist rationalization under pressure.

Build, dev-loop, and tooling conventions for OpenWhisper. READ before scripting dev commands, proposing build changes, picking a package manager, or shipping a Windows release bundle.

Cut a versioned OpenWhisper release (Mac DMG + Windows MSI) split across two physical machines via a draft GitHub Release. READ before bumping versions, tagging, building release artifacts, or writing a release-handover doc. Triggers when the user asks to "cut a release", "release vN.M.0", "ship X.Y.Z", or "do the release handover".

Iteration discipline rule — at most TWO code attempts at a misbehaving feature (initial implementation + one feedback-driven fix) before stopping to do deeper research. READ before reaching for a third "let me try X" change in response to "still not working" feedback. Applies to any feature implementation, bug fix, or platform integration where the first observable test contradicts what the code was supposed to do.

Architecture rule — state machines, phase transitions, gating logic, and status strings live in the Rust core, not the platform shell. READ before proposing where to put logic that touches the dictation state machine, phase transitions, gating rules, or anything the UI reacts to. The temptation on every new shell is to keep "just the UI-coupled bits" in the shell — resist.

Known Parakeet-TDT transcription quirks — what looks like a bug but is actually a model-level token behavior. READ before chasing a transcription quality issue through `core/src/audio.rs`, the FFI boundary, or the model-loading path. The right fix for items in this list is post-processing (custom vocab, DA rules) under the custom-vocab task in `backlog/` (currently `task-10`), not engine swaps or routing investigation.