Understand an unfamiliar codebase — either a full briefing (purpose, architecture, seams, design taste, commit-history rationale, standout code) or a scoped dataflow trace of one subsystem. Use when asked to "understand this repo", "explain this codebase", "give me a tour", "how does X work here", "trace how data flows", "where does this value come from", or "why is it designed this way". Do NOT use to assess repo health/popularity (use repo-eval) or to review a diff (use a code-review skill).
Review a change or audit existing code through the Russ Cox lens — necessity, layering, minimal seams, error/logging/testing discipline, and anti-bloat. Use when reviewing diffs, new features, or dependency additions, or when asked to "audit this package", "refactor/polish this code", "find design, implementation, or style problems", "do we need this?", or "is this too complex?". Do NOT use for public API shape or product-vs-library tradeoffs (use code-review-mitsuhiko) or invariant/cost honesty (use code-review-burntsushi).
Append quick captures — todos with due dates, log lines, learnings, reflections — to the right section of Obsidian daily (DailyPlan/) and weekly (Weekly/) notes. Use when asked to "add a todo", "note this down", "log this", "capture an idea", "due Friday", or to record something fun or a weekly reflection. Do NOT use for searching notes (use obsidian-vault-search) or for creating standalone long-form notes.
Search an Obsidian vault three ways — Meilisearch for topic and fuzzy queries, ripgrep for exact strings/tags/task glyphs, and a date-aware helper for natural-language dates and overdue math. Use when finding notes about a topic, half-remembered ideas, recent writing, tagged content, or due/overdue/high-priority tasks in a local Markdown vault. Do NOT use to add or edit notes (use obsidian-capture).
Write or critique a README for an open-source project (library, CLI tool, or agent tool) with an impatient-reader lens: concrete value first, shortest path to use, no duplicated claims, and reference material only when it earns space. Use when the user asks to "write a README", "draft a README", "review my README", "improve my README", or starts a new lib/tool and needs documentation. Do NOT use for internal service docs, monorepo root READMEs, or non-public projects.
Design or review command-line interface shape — flags, subcommands, help, errors, and output contracts — against established CLI conventions (clig.dev, POSIX, GNU). Use when the agent is about to write a CLI tool, add a subcommand, design flag names, review --help output, or evaluate CLI UX. Do NOT use for TUI/full-screen terminal apps, GUI design, or web API design.
Review code for API shape, error handling, backward compatibility, and product-vs-library fit. Use when reviewing public APIs, library interfaces, error types, dependency choices, or product code being over-engineered, or when deciding between "ship the dumb version" and "design for stability". Do NOT use for deletion-focused or anti-bloat review (use code-review-russ-cox).
Guide test writing and review with focus on observable behavior over implementation. Use when the user asks to write, review, or refactor tests; debates unit vs integration scope; questions whether to mock a dependency; or asks why tests break on refactor.