shaughv-code

Design, audit, and apply high-reliability prompts for difficult agentic work. Use for vague or underspecified consequential requests, prompts/system prompts/agent briefs, Claude Code or Codex instructions, multi-agent workflows, hard problems needing a better representation or method, complex software/data work, Erdős-level mathematics/science, and durable long-horizon tasks. Without a named mode, infer Author/Audit/Operate/Evaluate and relevant guidance from the latest active context, propose a compact working contract, ask concise material questions, and proceed. When orchestrating, compile every subagent brief with branch-specific context, oracle, loop policy, and return receipt. Tests load-bearing premises, selects information-bearing actions, and preserves truthful partial/blocked/refuted states. Route already-stalled work to loop-escape; keep routine work proportional.

Interactive bug triage and investigation agent for internal tools and platforms. Use this skill whenever a user reports a bug, issue, error, or unexpected behavior in an internal tool — or when they forward a bug report from an end-user. Also trigger when the user says "bug", "issue", "broken", "not working", "error", "something's wrong with", "investigate this", "triage this", "reproduce this", "bug report", "defect", or describes unexpected behavior in any internal system (internal dashboards, web apps, data platforms, admin tools, etc.). This skill actively investigates using browser tools and data platform queries — it doesn't just ask questions. If the user pastes a screenshot, error message, or Slack message about something broken, use this skill.

Advisory catalog for deciding whether to reuse or suggest the optional Remotion documentation, Shaughv Health, or Pipedream MCP connections without bundling or auto-installing them. Use when a task may benefit from live Remotion docs, private health-data tools, or Pipedream integrations; when an MCP appears missing, duplicated, or client-provided; or when the user asks how to connect, activate, install, scope, or reuse one of these services in Codex or Claude Code.

Gang of Four design patterns reference and analyzer. Covers all 22 GoF patterns (5 Creational, 7 Structural, 10 Behavioral) from refactoring.guru, with Python, TypeScript, and SQL examples. Trigger when the user names a pattern (Singleton, Factory, Strategy, Observer, Adapter, Decorator, Builder, Proxy, Facade), asks "what pattern fits", "how should I structure this", "is this over-engineered", "how do I refactor this", "what SOLID violation is this", or shows code that smells like a pattern — god objects, switch-on-type, deep inheritance, leaky abstractions, duplicated conditionals, hard-coded dependencies. Also trigger on "code smell", "anti-pattern", "tight coupling", or architectural review. REFERENCE + ANALYZER — names patterns, recommends them, flags anti-patterns. NOT the executor; hand multi-file refactors to a `refactoring` skill.

Seven agent-first thinking frameworks plus input inspection: Contemplating, Decision-Making, Design, Problem-Solving, Information Triage / Sensemaking, Scientific Inquiry, and Strategic / Adversarial (Art of War, 36 Stratagems, Five Rings, game theory). Use to slow down and audit your OWN work or facilitate a human. Trigger on "think through this", "make a decision", "I'm stuck", "challenge my assumptions", "try a different approach", "what's my play", "war-game this", "red-team my plan", or when a stalled approach needs reframing across genuinely different strategy families. Adds forced pause, divergence before convergence, sanity checks, assumption/bias discipline, steel-manning, and a lossless canvas. For repeated same-result/no-new-evidence execution cycles, start with loop-escape and use this skill to reframe; for oversized scope use iterative-plan; for formal evidence audits use logical-reasoning; for code defects use debugging-framework.

Upscale, enlarge, super-resolve, and enhance images and photos using fal.ai's Clarity Crystal Upscaler (clarityai/crystal-upscaler), purpose-built for faces, portraits, headshots, and profile pictures. Use this whenever the user wants to increase an image's resolution, make a picture bigger or sharper, fix a low-res or blurry photo, restore detail, clean up a compressed download, or prep an image for print or a high-DPI display, even if they don't say the word "upscale". Accepts JPEG, PNG, WebP, GIF, or AVIF as a local file (auto-uploaded), an http(s) URL, or a data URI; supports 1x-200x scale, creativity 0-10, and PNG or JPG output, and auto-shrinks oversized inputs under the 100 MiB API limit. Requires a FAL_KEY env var; bills per output megapixel.

Use when actively debugging a bug — an integration that drifted, a write that didn't land, a queued message that vanished, a 5xx with no logs, a datetime that's an hour off, an idempotency replay double-write, a config that silently dropped a field, a value that's NULL where data was expected. Triggers on phrases like "debug this", "why is X NULL / wrong / missing", "the data doesn't match", "this returns 500", "works locally but not in prod", "the sync is failing silently", "I've tried three fixes and...", "the test passes locally but fails in CI". Use this skill for the root-cause debug loop once something has already failed; for end-user-facing bug intake use bug-triage; for pre-emptive error-handling design use defensive-programming.

Use when writing or reviewing code at a system boundary (HTTP handler, RPC/tool entry, third-party API call, database row hydration, queue/message handler, serverless function trigger, CLI parse, config/env load), when authoring or critiquing a try-except block, when designing an error contract, when adding retry-backoff or timeout logic, when adding a feature flag as a safety net, when reviewing a diff that introduces null-checks or AssertionErrors, or when a code review surfaces broad exception swallowing, silent fallback behavior, or validation duplicated across internal layers. Tightens what "defensive" means so the codebase gets the safety without the noise.

How to use Google Cloud Storage (GCS) buckets end-to-end from the CLI and from code — upload, download, list, delete, "folders", public objects, signed URLs, CORS, lifecycle, and the URL formats you return to users. Use whenever the user mentions Google Cloud Storage, GCS, a GCS bucket, `gcloud storage`, `gsutil`, `gs://`, storage.googleapis.com, signed URLs for GCS, service-account JSON keys, `GOOGLE_APPLICATION_CREDENTIALS`, Application Default Credentials (ADC), uniform bucket-level access, making a bucket public, versioning, soft delete, or hierarchical-namespace (HNS) folders — or wants to upload an asset to a Google Cloud bucket and get back a shareable URL. Also use when diagnosing GCS 403 / SignatureDoesNotMatch / CORS / credentials / `gcloud` install errors. For the personal `shaughv` bucket, defer to the `shaughv-gcs-storage` skill instead. See the body's "When this skill fires" for the full trigger list and the safety rule.

Official git workflow and committing strategy for all repos. Use for branches, worktrees, workbranches, commits and messages, PRs, pushing, pulling, rebasing, merging, cleanup, conflicts, hotfixes, feature flags, multi-agent coordination, shipping, or questions about which branch or workflow to use. Also trigger on main, trunk, stale branches, force-push, direct/default-branch delivery, or getting code into production. Provides exact CLI guidance and strongly defaults to worktrees, daily workbranches, and gated PRs, while accepting clear owner approval for a simpler delivery route without skipping tests, validation, secret checks, or post-push CI.

Write a compact, evidence-typed handoff for a future agent or session. Use when ending or stopping mid-task, switching context, wrapping up for the day, approaching compaction, or when the user says "/handoff", "wrap up", "pick this up tomorrow/later", "before I close this", or "write up where we are." Preserves the objective and acceptance contract, authority and scope, verified state with evidence pointers, decisions, artifacts, live hypotheses, attempt ledger, failed routes and re-entry conditions, unresolved contradictions, open obligations, and the exact next bounded action. Keeps raw chronology at stable paths instead of dumping the transcript into active context. When an active task system already owns the continuation packet, update that canonical task record first and create a standalone docs/agents/handoff/YYYY-MM-DD-NNN-SLUG.md only on explicit request or when no task record owns the work. Defers to git-workflow for any commit.

Create or update a HUMAN_CHANGELOG.md in a repo by translating the existing CHANGELOG.md into plain-English, layman's-terms entries (no version numbers, no variable names, no technical jargon — just what changed and why). Also wires up the repo's CLAUDE.md (creating it if missing) with a standing instruction that any agent updating CHANGELOG.md must update HUMAN_CHANGELOG.md in lockstep. Use whenever the user says "human changelog", "humanize the changelog", "plain-English changelog", "non-technical changelog", "translate the changelog", "make a readable changelog", "set up HUMAN_CHANGELOG", or asks for a changelog a non-engineer can read. Also trigger when the user wants agents to automatically keep a human-readable changelog in sync with a technical one.

Use whenever the user wants to generate, create, make, draw, edit, modify, retouch, transform, restyle, remix, blend, upscale, or remove-the-background-from an image — text-to-image or image-to-image — even if they don't name a model. Routes to Nano Banana 2 / Gemini (Google) — via fal.ai or the native Gemini API — MAI-Image-2.5 (Microsoft) via fal.ai, or Reve (api.reve.com), always asking which provider to use first and noting each one's cost/quality. Saves results to the user's Downloads folder. Trigger on "generate an image", "make me a picture/logo/poster/icon", "edit this photo", "change the background", "upscale this", "blend these photos", "remix these", and similar — do not try to satisfy these with anything other than this skill.

Milestone planning and recovery for work between a request and a demoable hand-back. Walks Clarify, Profile, Spine, and the Slice loop; owns the binary/demoable success criterion. Trigger on "plan this milestone", "scope this out", "help me write the tasks", "what's our first slice", "task is too ambitious", "get the basic version working first", "break it into steps", "is this slice too big", a vague "works well" / "is ready" / "Foundation complete", an overloaded milestone set, or materially identical evidence cycles that require stop-the-line route review. Preserves the real end goal while separating the smallest end-to-end functional rung, integration/hardening, and remaining qualification. Applies to Jira epics, Notion briefs, roadmaps, and Markdown plans. Pair with loop-escape for repeated no-information execution, critical- thinking for reframing, and logical-reasoning for evidence audits. Fights overplanning and Waterfall.

Guided facilitation for deliberate learning. Detects which kind of session is happening — Kickoff (new topic, build goal + syllabus + journal), Session (mid-journey, run one Learning Loop iteration), Review (weekly journal review), or Course-Correct (stuck or plateauing) — and routes accordingly. Built around the proficiency levels (Unaware → Master), Goal Setting, Meta-Learning Research, the Learning Loop (Choose Chunk → Plan Feedback → Practice → Retain), and the Learning Journal as the living artifact. Includes cognitive scaffolds — chunking, encoding hierarchy, active recall, spaced repetition. Use whenever the user says "help me learn", "I want to learn", "I'm learning", "teach me about", "I'm studying", "what should I focus on", "review my learning journal", "I'm stuck on", "I've been plateauing", "create a syllabus", or any variation about deliberate skill or subject acquisition. Also trigger when the user shows up with a learning journal, syllabus, or sources to study. When in doubt, trigger.

Rigorous deductive and inductive reasoning for an agent auditing its OWN load-bearing conclusion. Use to evaluate arguments, build/check proofs, test validity, symbolize language, name fallacies, weigh statistical/analogical evidence, or compare explanations. Also trigger on "does this retry add evidence?", "same result again", "are these attempts independent?", "is this valid?", "does this follow?", "prove that", "what's the fallacy", "sound or unsound", or "how strong is this evidence?" Audits repeated attempts by comparing starting state, intervention, observation, and information gained, then classifies them as new evidence, valid replication, or duplicate cycles; correlated retries do not become independent support. Pair with loop-escape when execution is stuck, critical-thinking for open-ended reframing, and iterative-plan when scope needs a smaller end-to-end rung. This skill owns formal rigor.

Recover work that is stuck, going in circles, repeating the same result, or running without new evidence. Use when an agent repeats a command/check/tool, the current candidate is invisible to the deciding oracle, nobody can state the last verified state, the task is too ambitious, or the operator says "get the basic version working," "try a different approach," "we learned nothing," or "does another retry help?" Builds causal attempt signatures, distinguishes productive iteration, valid replication, and duplicate routes, classifies token, epistemic, action-policy, and false-premise loops, repairs observability, and re-enters through a discriminating action. Self-contained; sibling skills add optional depth. Do not trigger for passive monitoring, expected long operations, materially changed experiments, or predeclared independent replication.

Comprehensive guide to the Mistral AI API end to end, with OCR, audio transcription (Voxtral), and text-to-speech as the primary use cases. Use whenever the user mentions Mistral, mistral.ai, api.mistral.ai, La Plateforme, MISTRAL_API_KEY, or any Mistral capability — OCR / document understanding / PDF-to-Markdown, audio transcription, text-to-speech / voices, chat completions, tool calling, structured JSON, vision, embeddings, FIM / code completion, moderation & classification, files, batch, fine-tuning, or the Agents & Conversations API. Also use when wiring a Mistral key into a project, when a request hits api.mistral.ai, or when you see model ids like mistral-large-latest, mistral-small-latest, voxtral-*, or mistral-ocr-*. See the body's "When this skill fires" for the full trigger surface.

Use whenever you are about to name ANYTHING in SHAUGHV brand work or in one of Emmett's repos (whether under the `RealEmmettS` or `QubeTX` GitHub org) — a variable, function, class, constant, boolean, file, folder, Git repo, branch, commit message, pull request title, feature flag, database column, migration, or any other identifier. Also when reviewing a rename, reading a name and unsure if compliant, or when the user hands you a tool-junk filename (Teams timestamps, ChatGPT exports, copy markers, FINAL/WORKING/DRAFT flags). Carries SHAUGHV-specific conventions (kebab-case repo names under `C:\Users\hey\git\`, `main` default branch, Conventional Commits) plus the universal principles from Code Complete 2 (Steve McConnell, Microsoft Press, 2004) and The DevOps Handbook (Kim, Humble, Debois, Willis, IT Revolution, 2016/2021). Triggers on ANY naming decision — even ones that feel "obvious" — because naming compounds and agents under-trigger naming skills.

Use when building anything that involves OpenAI's audio stack — Realtime API (gpt-realtime-2, gpt-realtime, gpt-realtime-1.5) for low-latency speech-to-speech voice agents; gpt-realtime-whisper for live transcription; gpt-realtime-translate for live translation; gpt-4o-mini-tts / tts-1 for text-to-speech; gpt-4o-transcribe / gpt-4o-transcribe-diarize / whisper-1 for file-based speech-to-text; or gpt-audio for audio inside Chat Completions. Triggers on phrases like "voice agent", "real-time voice", "speech-to-speech", "live captions", "live transcription", "real-time translation", "narrate text", "generate spoken audio", "TTS", "phone call AI", "telephony", "SIP", "WebRTC OpenAI", "WebSocket OpenAI Realtime", "stream audio from microphone", "voice assistant with tools", "speech recognition", and any mention of the model IDs above. Covers WebRTC, WebSocket, and SIP transports plus session lifecycle, tool calling, MCP, prompting, cost management, and beta-to-GA migration.

A personal productivity toolbox distilled from five books — Four Thousand Weeks and Meditations for Mortals (Oliver Burkeman), Slow Productivity and Deep Work (Cal Newport), and Procrastinate on Purpose (Rory Vaden). Use this skill whenever the user is prioritizing a task or operator list, planning the upcoming week, deciding what to work on, feeling overloaded or behind, asking how to balance their time and effort, or wondering what to drop, defer, or delegate. Trigger it for "help me plan my week", "prioritize my list", "what should I focus on", "I have too much to do", "I'm overwhelmed", "review my tasks", "how do I get this done", or any variation about managing finite time and attention — even when the user doesn't name a framework. When in doubt about whether a productivity question would benefit from these frameworks, trigger it.

DOM-free text measurement and line layout using @chenglou/pretext. Use when building with or integrating the Pretext library for text height calculation, line layout, shrinkwrap/orphan prevention, multi-column text flow, obstacle-aware text routing, masonry layouts, or any scenario needing DOM-reflow-free text measurement. Triggers on imports from @chenglou/pretext, mentions of Pretext library, DOM-free text measurement, canvas measureText layout, or references to prepare/layout/layoutWithLines/walkLineRanges/layoutNextLine functions. Also use when setting up Pretext in Next.js, Vite, or vanilla projects, or building React integration hooks/components for Pretext.

Expert at working with Quiver AI's Arrow model for SVG generation. Use this skill whenever the user wants to generate SVG graphics, create vector logos/icons/illustrations, write prompts for Quiver AI, make API calls to the Quiver AI API, vectorize raster images to SVG, or do anything involving quiver.ai or the Arrow model. This includes when someone says things like "make me an SVG", "generate a logo", "create a vector icon", "write a Quiver prompt", "vectorize this image", or mentions quiver.ai, Arrow model, or text-to-SVG in any context.

Use for any security work on a repo or branch — "security check", "security audit", "security review", "check for vulnerabilities", "is this safe to push/merge/ship", "scan for secrets", "OWASP", "PII or data exposure" — a pre-merge impact read: "how big is this change", "will this break main", "breaking change", "blast radius" — or adversarial testing: "red-team this", "try to break this", "pen-test". Four modes: full-repo audit (comprehensive report: vulns, auth posture, sensitive-data map, supply chain), branch/diff security review, merge-impact assessment (% repo affected + breaking signals), and on-request red-team (STRIDE + WSTG attack battery). Stack-aware — if your stack includes React/Vite, Azure Functions, FastAPI, Rust, Azure SQL, MSAL/Entra, SWA/Bicep/Key Vault, LLM/MCP, or CI/Docker, it fingerprints the repo and loads only the matching references. Output: chat summary + dated report in security-audit/. When in doubt before a push/merge, trigger.

Build the SHAUGHV animated brand mark -- an SVG logo that draws itself path-by-path with stroke animation, transitions to solid fill, then alternates between a full wordmark and an icon variant in a continuous loop. Use this skill when asked to create, recreate, or implement the SHAUGHV animated logo, animated brand mark, drawn SVG logo, SVG draw/undraw animation, or any animated logo that alternates between two SVG states with path-drawing effects. Also use when someone says "animate the SHAUGHV logo", "draw-on SVG animation", "brand mark animation", or references the SHAUGHV/Shaughv brand identity animation.

Discover and consume assets from the SHAUGHV CDN at cdn.shaughv.com through its live /agents guide and /tree.json manifest. Use whenever a task mentions the SHAUGHV CDN, a cdn.shaughv.com or cdn.emmetts.dev URL, SHAUGHV-hosted fonts, brand assets, images, favicons, figurines, scripts, loaders, embeds, or preloads. Fetch the live catalog instead of relying on remembered family names, file paths, formats, counts, snippets, or licensing notes.

Create or update SHAUGHV-branded sites, interfaces, footers, and visual assets for Emmett Shaughnessy. Includes the paired wordmark and crest footer, proportional logo scaling, local logo assets and fonts, Makira and Paper Mono guidance, optional CDN fonts, motion, palettes, and reference UI kits. Use when installing SHAUGHV branding or adapting its footer to an existing site's theme.

How to upload to, download from, and manage Emmett's personal public Google Cloud Storage bucket at `gs://shaughv`, returning shareable URLs of the form `https://storage.googleapis.com/shaughv/<path>`. Use whenever the user mentions the `shaughv` bucket, `gs://shaughv`, `storage.googleapis.com/shaughv`, Emmett's personal GCS bucket, "upload to shaughv", or asks to share / publish / stage an asset for Emmett that needs a real URL — and is NOT a SHAUGHV brand asset (those live on cdn.shaughv.com via the `shaughv-cdn` skill). Also when the user says "put this on my bucket / on GCS / on Cloud Storage" or "stage this for me" in a SHAUGHV or Emmett-personal context. Bucket facts are pre-wired so the agent never has to ask. For general GCS concepts or any bucket OTHER than `shaughv`, defer to `gcs-storage`. See the body's "When this skill fires" for the full trigger list.

The operator's standing model/effort convention for EVERY subagent — the Agent tool (including Explore/Plan agents), Workflow agent() calls, custom agent types, any dispatch. Trigger whenever spawning a subagent, choosing a model or effort/reasoning level for one, writing a Workflow script's model/effort params, or authoring a dispatch prompt; also when a new Anthropic lineup ships (the mapping-forward procedure lives here) or when installing the rule into a repo/machine (paste-able snippets in references/). Short form: Opus 5 [1m] at xhigh (max when needed) for deep work; Sonnet 5 at max (xhigh when lighter) for fan-out; never Haiku/budget classes, never auto-substitute Fable or Mythos, never below xhigh. Set 2026-07-24 per Emmett. Scope: Claude Code / Anthropic harnesses only — non-Anthropic agents should ignore this skill.

Use when anyone asks for a "TT;DR" (also "TTDR" or a "too tired didn't read" summary), or whenever you're about to hand back a status update, progress report, decision, commit or PR description, incident write-up, or any long or detailed answer and want to open it with a short skim-summary for a busy or tired reader. A TT;DR is a short (1–3 sentence), plain-English, high-level lead that sits on top of the detailed information rather than replacing it — the full answer still follows beneath it. Covers what a TT;DR is, how to write one for the context at hand, and how it differs from a TL;DR, a technical overview, or a tech spec. Trigger phrases: "TT;DR", "TTDR", "give me a TT;DR", "too tired didn't read", "lead with a summary", "high-level summary first", "skim summary", "what does TT;DR mean", "TL;DR vs TT;DR".

Install and standardize Emmett's Claude Code usage status line — a two-row status line showing live 5-hour and weekly usage percentages with color-coded progress bars, plus a burn-rate estimate of how much time is left before the 5-hour limit is hit at the current pace (with a red/green trend indicator). Use this whenever the user wants to set up, install, reinstall, or standardize their Claude Code status line; show usage / rate-limit percentages in the status line; add a 5h or weekly usage bar, burn-rate, or "time left" / "time until reset" indicator; replicate this status line on a new machine; or verify, customize, troubleshoot, or uninstall it. The canonical, byte-identical script ships with this skill so every machine that has the plugin can reproduce the exact same status line on request. Requires Node.js ≥18; the live usage numbers appear only on Pro/Max subscription sessions.

Use wb300 to inspect or supervise Git branches, worktrees, and the coding agents running across them. Trigger this skill whenever the user wants to know what branches / workbranches / worktrees / agents are active, "what agents are running and on which branch", which branches are uncommitted / committed / pushed / merged / ready to review, what's safe to clean up, or where two branches will collide at merge time — across one repo or the whole machine. Also trigger whenever wb300 is named directly ("wb300", "wb300 agent", "wb300 help", "the workbranch view", "the branch control tower"), when you need a machine-readable snapshot of branch/worktree/agent state to orchestrate other work, or when the user wants to install / update / uninstall wb300. Prefer this skill over ad-hoc `git branch` / `git worktree list` whenever wb300 is available, because it derives the real branch hierarchy from Git's commit graph and overlays live process and remote signals in one shot.

Analyze and improve a repeatable workflow or process with proportional evidence, not mandatory ceremony. Use when someone asks to optimize, streamline, redesign, audit, map, document, or fix how work moves end to end; when a process is slow, broken, variable, wasteful, or bottlenecked; or when designing a new operating workflow. Offers a focused mode for one bottleneck and a comprehensive mode for broad/high-risk audits. Contracts the outcome, reconstructs the current process, measures a baseline, selects only applicable Lean, Six Sigma, Theory of Constraints, TQM, BPR, and Process Optimization lenses, pilots the smallest discriminating change, and remeasures the result. Diagramming and multi-turn clarification are conditional. For Agile/Scrum methodology prefer agile; for milestone shaping prefer iterative-plan.