0xa3b/engineering

Design deeper module interfaces and better seams in concrete repository code. Use when asked to design or improve a specific module interface, deepen shallow wrappers, compare interface designs, choose a seam, reduce caller knowledge, improve testability through an interface, or when another workflow or review lane directs applying engineering:codebase-design. Do not use for direct bug fixes, generic code review, implementation-only requests, or conceptual architecture questions.

Review dependency update PRs across package managers and forges, decide whether they are safe to merge, merge only ready updates, sync local dependency state, refresh repo-pinned tooling through small maintenance PRs, and create linked follow-up issues for breaking changes, validation failures, or useful new features. Use when the user asks to review Dependabot, Renovate, lockfile maintenance, security, runtime, package-manager, or other dependency update PRs.

Run a disciplined diagnosis loop for bugs, failures, flaky behavior, and performance regressions: build a red-capable loop, reproduce and minimize, rank falsifiable hypotheses, instrument, fix, and regression-test. Use when the user explicitly asks to diagnose or debug a problem.

Interview the user through an adversarial decision tree until the important decisions, dependencies, and edge cases are clear. Use when the user asks to stress-test a plan, decision, idea, or design, get grilled on an approach, challenge a brainstormed direction, or resolve ambiguity before implementation.

Compact the current session into a local handoff document so another agent session can continue without reconstructing decisions, state, and next actions.

Find evidence-backed architectural deepening opportunities in a codebase. Use when the user wants refactoring candidates, better module design, simpler interfaces, stronger testability, or a focused codebase architecture review.

Find evidence-backed test-suite improvement opportunities in a codebase. Use when the user wants the test suite treated as a codebase: flaky or slow suites, scaffold and fixture design, mock strategy drift, subsumed or low-value tests, or a focused test-suite health review. Do not use for reviewing the tests of a single diff or branch, which belongs to the test-review lane of a code review.

Build a disposable prototype that answers one design question before real implementation. Use when the user asks to prototype, spike, or try a throwaway version of something, sanity-check a state model or data shape, compare design approaches with switchable variants, or prove that an existing system accepts a change before committing to it, and when engineering:grill-me, engineering:wayfinder, or engineering:tdd needs executable evidence for an open decision. Do not use for code intended to land, which belongs to engineering:tdd; for a bug whose cause is unknown, which needs diagnosis first; for reviewing existing changes; or for conceptual questions about prototyping.

Use when handling existing feedback that evaluates completed work: reviewer comments, PR or MR comments, sub-agent findings, findings from a review agent or bot, or a user's correction of a prior response. Verifies and triages each item before responding or applying fixes. Do not use for a message that extends the active task rather than evaluating completed work, such as accepting a recommendation, adding a requirement, or supplying implementation details; for first-party bug reports; for implementation requests; or for requests to generate a new code review.

Use when asked to review changes made in the current session before committing, opening a PR, or merging: the worktree, staged or work-in-progress edits, or the session's commits up to a whole branch, including changes to agent-instruction files and documentation. Also use when asked to run one review lane, such as test quality or prose, over those changes. Runs focused review lanes with independent reviewers, verifies and triages the findings, applies accepted in-scope fixes, reruns the lanes those fixes invalidated, and validates. Do not use for a branch, PR, or MR someone else authored; for existing reviewer feedback; for first-party bug reports; for implementation requests; for architecture or test-suite audits of a whole codebase; for writing documentation; or for conceptual questions about review.

Use when implementing or changing behavior that callers or users can observe: a new feature, a behavior change, a bug fix whose cause is known, a port from a reference implementation, or a new or changed public interface or seam. Drives the work through a red-green-refactor loop over a frontier of behaviors, with tests at the public interface. Do not use for changes with no behavior to prove, such as configuration, documentation, formatting, or mechanical renames; for disposable prototypes or spikes; for a bug whose cause is still unknown, which needs diagnosis first; for reviewing existing changes; or for conceptual questions about TDD.

Create, update, prune, or review durable project terminology in AGENTS.md. Use when the user wants to define domain terms, harden naming, resolve ambiguous language, record aliases to avoid, align code or docs with a terminology section, capture a term that stabilized during review or implementation, or adapt glossary/ubiquitous-language guidance into repository agent guidance. Do not use for general instruction-file style or structure editing, for renaming code identifiers without a terminology decision, or for conceptual questions about terminology or domain language.

Turn a loose or oversized idea into a breadth-first map of its destination, known facts, open decisions, decision-sized chunks, dependencies, frontier, unresolved fog, and excluded scope. Use when the user wants to brainstorm, scope a large effort, decompose an unclear goal, or find the next decisions before deeper planning or implementation.