swe-assistant

Use when the user is about to ask a colleague for help, is hesitating to ask (worried about being annoying or seeming inexperienced), is preparing or drafting a question, has been stuck a while and wondering whether to keep digging or ask, or is reflecting on whether they ask too much or too little. Triggers include "I have a question for X", "I don't want to interrupt", "how do I ask without sounding dumb", "I've been stuck for hours", "should I ask or keep trying", "how should I frame this question", "I feel like I'm always asking my teammate things", or asking how to balance independence with getting help. Walks through the asking-for-help framework from The Missing Readme (Chapter 2) — do your research first, timebox before asking, show your work when you do, respect others' focus, prefer multicast and async communication, batch synchronous requests. Goal — be neither a drain (asks too much, never tries) nor a martyr (never asks, burns hours alone). Do not trigger when the user is asking the AI assistant directly or asking how to prompt AI tools — those have different dynamics, covered elsewhere.

Use when the user is considering a meaningful change to the existing way things work — proposing a rewrite of a module or system, wanting to bypass or break a team coding standard or convention, talking about forking a library or framework instead of contributing upstream, or proposing to swap one technology for another in the stack. Triggers include phrases like "I want to rewrite this", "let me migrate us from X to Y", "we should replace [tool] with [other tool]", "I'm going to fork the library to fix this", "I don't agree with our coding standards", "let me just bypass the linter rule", "this whole module needs a rewrite", "let's switch from X to Y framework", or asking whether some kind of large change to existing code, conventions, or stack is a good idea. Walks through the four pitfalls from The Missing Readme (Chapter 3) — rewrites, going rogue on standards, forking without upstreaming, adding new technologies — using Horowitz's "10x better" rule as the decision criterion. For new-technology evaluation specifically, route to choose-boring-technology. Do not trigger for small in-flight refactors, code reviews, or active incidents.

Use when the user is about to modify existing code — especially code that is unfamiliar, untested, complex, or scary to touch — and wants to do it safely. Triggers include phrases like "I need to change this old code", "how do I refactor this safely", "this code has no tests how do I touch it", "I'm scared to change this", "about to modify a legacy system", "how should I structure this refactor", "how do I add a feature to this messy code", "should I rewrite this or work with what's there", or asking about safely changing existing code. Walks through Michael Feathers' Legacy Code Change Algorithm (identify change points, find test points, break dependencies, write tests, then make the actual change and refactor), the standard dependency-breaking techniques (extract methods, introduce interfaces, inject control points), the leave-cleaner-than-you-found-it discipline applied opportunistically, the incremental-PR rhythm, and pragmatism about when refactoring is worth the cost. Do not trigger for greenfield code, for tactical syntax or API questions, or for active code reviews (route to code-review).

Use when the user is evaluating, proposing, or being pulled toward adding a new technology to a stack — a new programming language, framework, database, library, build tool, deployment platform, or any meaningful new dependency. Triggers include phrases like "should we use [X framework / language / tool]", "I want to introduce [tech] to our stack", "let's switch from X to Y", "what's the best language for this project", "evaluating [tech] for [purpose]", "I think we should adopt [new thing]", "is [new tech] worth it", or asking about the trade-offs of any new-tech adoption decision. Walks through the boring-technology framework from The Missing Readme (Chapter 3, citing Dan McKinley's Choose Boring Technology) — the concept of innovation tokens, the ecosystem-maturity evaluation criteria (packaging, IDE, libraries, tests, engineer market, performance, integrations), and the cost-vs-benefit framework that determines whether the new technology earns its token. Do not trigger for in-stack technical questions (how to use a tool already chosen), for code reviews, or for the broader question of "should we change X" that isn't specifically about technology adoption (route to change-discipline).

Use when the user is about to review someone else's pull request or merge request, has been asked to review code, is in the middle of leaving feedback on a PR, is on the receiving end of code review feedback (especially feedback that feels confusing, harsh, or unclear), or is asking how to give or receive code reviews well. Walks through how to give a good review — order of priorities (correctness, security, maintainability, clarity, then style), tone (questions over commands, suggest don't dictate), what to label as blocking vs nit, what to skip if a linter handles it, and when to praise. Also covers receiving reviews well — separating the code from the self, asking for clarification, when to push back with reasoning. Useful at any stage from Ramp-Up onward; central to the Contributor stage. Do not trigger for general engineering questions, debugging, or asks about how to *write* code from scratch — only when the situation is reviewing or being reviewed.