dotfiles

Guide for designing and writing Claude Code hooks. MUST be invoked when creating a new hook, adding hooks to settings.json, debugging hook behavior, understanding what hook events are available and what JSON they receive, or implementing patterns like behavior correction, pre-stop checklists, context injection, side effects, and permission control.

PostgreSQL performance: find slow queries, read plans, and tune indexes, writes, and server config. MUST be invoked when a Postgres query is slow, a query needs an index, EXPLAIN shows a Seq Scan on a large table, inserts or bulk loads are slow, autovacuum/bloat is suspected, or you're choosing index types or server settings. Covers pg_stat_statements, EXPLAIN (ANALYZE, BUFFERS), index types (btree/partial/expression/covering, GIN, GiST, BRIN), ANALYZE and autovacuum, COPY and bulk-load tuning, and the shared_buffers / work_mem / effective_cache_size baseline.

Make a pytest suite faster and more trustworthy. MUST be invoked when a pytest run is slow, CI test time needs cutting, a suite should be parallelized, or tests are flaky/order-dependent. Covers measuring with --durations and pytest-durations, diagnosing fixture-scope waste (make read-only, then widen), replacing time.sleep with deterministic synchronization, parallelizing with pytest-xdist (-n, --dist worksteal/loadscope/loadgroup), hardening isolation with pytest-randomly so flakiness surfaces before CI, and cutting startup cost (collection, imports, coverage backend, testpaths, running fewer tests).

Python performance profiling and optimization. MUST be invoked when investigating CPU hotspots, memory usage, I/O slowness, async event loop blocking, or when optimizing slow Python code. Covers tools (cProfile, line_profiler, austin/speedscope, scalene), flamegraph generation, common optimization patterns (concurrent awaits, regex combining, recursive memoization, eliminating duplicate work, moving blocking I/O off the event loop), and profiling Python processes in Kubernetes pods.

SQLite performance: query optimization plus write and connection tuning. MUST be invoked when a SQLite query is slow, a query needs an index, EXPLAIN QUERY PLAN shows a full-table SCAN, inserts/writes are slow, or you're choosing an index or connection PRAGMAs. Covers reading EXPLAIN QUERY PLAN, the experimental `.expert` index recommender, index types (covering, expression, partial), ANALYZE / sqlite_stat1, transaction and bulk-insert speed, and the WAL + synchronous=NORMAL connection PRAGMA baseline.

Create, improve, and troubleshoot Claude Code agent skills. MUST be invoked when asked to make a new skill, write a SKILL.md file, improve skill discoverability, debug why a skill isn't activating, answer questions about skills, or review skill best practices.

Review recent Claude Code sessions (one project or all) and turn recurring friction, corrections, insights, and tool-usage lessons into rules, skills, or hooks, for your global Claude config or a project's own local one. Fans out a subagent per session for open-ended analysis, then synthesizes cross-session themes. Ships a script that turns noisy jsonl transcripts into clean, labeled conversation. MUST be invoked when asked to review or analyze recent sessions, mine transcripts for rule or skill ideas, find "what I've been correcting Claude on", or turn session history into config improvements. Routes findings to the rule-curator, skill-creator, and hook-creator skills.

Distill the current branch's working memory into its journal at branch-journals/<branch>.md — decisions and the why behind them, open questions, dead-ends not to revisit, and next steps, richer than a commit message. MUST be invoked when the user says "checkpoint", "update the journal", "save working memory", or "note this for later". The journal is git-ignored and ephemeral (it dies with the branch); it is resurfaced at session start by the `claude-branch-journal` command.

Review the user's Claude Code configuration (settings.json permissions, hooks, skills, rules, CLAUDE.md, bin/ hook scripts) and surface concrete opportunities to improve, refine, consolidate, remove, or add to it. MUST be invoked when the user asks to review/audit/critique their Claude config, asks "what could be better about my setup", wants to prune dead or redundant config, or wants ideas for new hooks/skills/rules/permissions. SHOULD be invoked proactively when work repeatedly trips over a missing guardrail or a repeated manual step that config could automate.

Ingest new material (articles, docs, snippets, reference links, code review feedback) and fold it into the rules in `claude/rules/`. MUST be invoked when the user shares a new convention, style guide, blog post, library doc, or reference and wants it captured, when deciding whether guidance belongs in an existing rule or needs a new one, or when auditing or refreshing rules with fresh material.

Debug GitHub Actions (GHA) workflow run failures. MUST be invoked when a CI/CD run failed, a workflow is broken, steps are erroring, a job was cancelled or timed out, or the user wants to investigate what happened in a specific run. Covers fetching logs, reading job/step output, and identifying root causes.

Fetch and address GitHub PR review comments and feedback on the current branch. MUST be invoked when asked to handle review comments, address reviewer feedback, fix review threads, check what reviewers said, work through unresolved comments, or respond to PR review requests. MUST also invoke when the user says "review comments", "PR feedback", or "address comments".