dotfiles

Structural code search and refactoring via ast-grep. Reach for this when Edit fails with 'old_string not unique', when refactoring across formatting variations, or when matching code shape rather than text.

Get an outline (functions/classes/exports) of a file or package without reading it whole. Use when the question is 'list/show/what's in' rather than 'where is' (search) or 'how does it work' (read).

Use when deciding whether to add a third-party dependency or library, or when evaluating an existing one (npm install, pip install, go get, cargo add, adding to a manifest). Covers crypto/security deps, the build-it-yourself threshold, and transitive-tree risk.

Extract a known field from a JSON file by running jq instead of reading the whole file.

Use when working in a Python repo and about to run python, pip, pytest, ruff, mypy, or any Python tool. Resolves the project virtualenv and requires full ./venv/bin/<tool> paths in all commands, plan files, and subagent prompts. Never run bare pytest or python.

Use when producing substantial prose -- docs, READMEs, design notes, PR descriptions, commit messages, long explanations, or report writeups. The full Strunk & White economy rules, the cut-list of needless constructions, the AI-tell vocabulary blocklist, and cadence guidance. The two always-on guardrails (no em-dashes, avoid AI tells) live in AGENTS.md.

Extract a known field from a YAML file by running yq instead of reading the whole file.