effective-engineer-setup

Draft or update an Architecture Decision Record (ADR) in docs/adrs/. Use whenever the user is choosing between design alternatives, introducing a new library/framework/database, defining a service boundary, reversing a past decision, or when a PR review surfaces "why did we do it this way?". Produces a numbered ADR file following the Nygard-style template (Context, Decision, Status, Consequences) plus an Alternatives Considered section.

Scan the codebase, PR, or recent conversation for the 20 individual-contributor and team-level anti-patterns catalogued in The Effective Software Engineer (Ch. 5 & Ch. 10). Use when the user asks "what smells?", "code smells", "am I doing anything wrong?", before a retrospective, when onboarding to a new codebase, or when a PR feels off. Produces a report listing each detected anti-pattern with evidence (file:line, commit, or quoted conversation) and the remedy from the book. Deliberately conservative — reports only anti-patterns it can cite evidence for.

Append a one-line accomplishment to docs/BRAG.md, or summarize entries from a time window. Use when the user says "log this", "add to my brag doc", "record this", after shipping something meaningful, or when prepping for a 1:1, self-review, or promo packet. Subcommands via first argument; `add` is default. Also invoked automatically by the Stop hook at the end of substantive turns (see .claude/hooks/brag-log.sh).

Stage and write a disciplined Conventional-Commit message for the current changes. Use when the user says "commit", "let's commit this", "make the commit", or when finishing a TDD loop. Inspects the staged and unstaged diffs, groups changes by concern, and either produces ONE commit if the diff is cohesive, or proposes a split into multiple commits if it is not. Never commits without showing the message first.

Record, list, or repay an item in the technical-debt ledger at docs/TECH_DEBT.md. Use whenever a shortcut is taken in the current change (hard-coded value, bypassed validation, skipped test, out-of-band config, copied-and-tweaked code), when the user says "let's come back to this" or "add a TODO", or when exploring the codebase reveals a debt item worth recording. Subcommands, selected via the first argument: `add`, `list`, `repay`, `audit`.

Drive a disciplined, hypothesis-based debugging loop for a bug, failing test, flaky test, or unexpected behavior. Use when the user reports "it's broken", pastes an error or stack trace, shows a failing test, or says "why is this happening?". Forces a written hypothesis before any code change, records what was tried, and converges by bisection rather than by guessing. Not for feature work — use /tdd for new behavior.

Reframe a task around its outcome before any code is written. Use at the start of any new feature, bug-fix, refactor, or when the user's request reads like an output ("add a button", "write a script", "build an endpoint") without a stated "so that…". Also use when the user asks "what should I work on?" or when scope feels fuzzy. The goal is a one-sentence outcome that names the user, the action, and the measurable result.

Produce the three artifacts that should exist AFTER code ships but are routinely skipped — a README/changelog update, an observability plan (metrics, logs, alerts), and a communication note (announcement draft for Slack/email/changelog). Use when a feature has been merged or is about to deploy, when the user says "we shipped it" or "announce this", or on your own initiative right after a /commit that closes a notable outcome. Explicitly refuses to treat the code-merge as "done".

Rank a set of candidate tasks, bugs, or ideas by impact and effort so the user knows what to do next. Use when the user lists multiple things ("we need to do X, Y, Z, and also Q"), asks "what should I work on?", presents a full backlog or a sprint candidate list, or is weighing two directions. Produces a 2×2 impact/effort table plus a one-sentence recommendation with the reasoning. Does not invent new items.

Facilitate a structured retrospective over a given period (sprint, project, incident). Use when the user says "let's do a retro", "look back on last week/sprint", "what did we learn from X incident", or when closing out a significant project. Produces a report with three sections (Kept, Changed, Action Items) where every action item has an owner, an acceptance test, and a due date. Explicitly refuses to produce action-less "it was fine" retros.

Run a structured code review over the current diff (or a named commit/branch) and produce a review report organized by severity. Invoke before asking a human reviewer, after finishing an implementation, or when the user pastes a PR URL/diff. Critiques only — does not rewrite code without a separate request. Forks an isolated reviewer subagent so the review cannot be biased by the current conversation.

Detect scope creep in the current task and propose a split. Use when the user adds "while you're at it…", "also can you…", or "one more thing…" to an in-flight task; when a diff grows past ~400 changed lines; when a PR description lists more than one outcome; or when Claude finds itself about to touch unrelated files. Output is a short assessment: stay the course, or split into N follow-up tasks with suggested titles.

Drive a feature or bug-fix through a tests-first loop (red → green → refactor). Use whenever the task is to add new behavior, fix a reproducible bug, or harden an existing function. Writes failing tests first, runs them to confirm they fail for the right reason, then implements the minimum code to turn them green, then refactors. Do NOT use for exploratory spikes, UI tweaks with no logic, or pure documentation changes.