AI Agent Workflow Collection

Use before showing any prose a human will read - docs, README, commit bodies, UI copy, store text. Run a read-back pass and cut the tells that make writing sound machine-generated, so it reads like a person wrote it.

Use before adding any cross-cutting change - a new gate, limit, permission check, or rule that must apply everywhere. Find ALL the places the action can happen first, not just the obvious one in front of you.

Use before building or agreeing to build something - push back when the work is unnecessary, over-complex, fragile, or heavier than the value it returns. Saying "skip this" or "simpler is enough" is part of the job.

Use when you hit a bug while building on your own shared code - a library, base class, SDK, or component. Fix it in the shared layer so every other caller inherits the fix, instead of patching around it in the one spot that surfaced it.

Use when fixing any bug - find the layer that creates the bad state and fix it there, instead of patching the symptom where it happened to surface.

Use before you call complex or shippable work done - get a fresh, independent review of the whole change. Your own pass plus green tests is not enough; you read past your own mistakes.

Use while building any mechanic that could fail on a machine you can't reach - a shipped product, a CLI a user runs, a server. Instrument it as you write it so that one verbose log dump from a stranger is enough to reconstruct what happened.

Use when you notice an incidental correctness problem (a stale comment, a wrong doc line, a drifted reference) in the area you're already editing - surface it and get the user's OK before fixing it, and stay inside the area you're already touching.

Use when adding or changing any feature - project it onto every part of the system it touches (cache, notifications, persistence, undo, permissions, search, tests), not just the code directly in front of you.

Use when stuck after several failed fixes on the same hypothesis - step back and question whether you're fixing the right layer at all, before trying the next fix. Being data-driven inside a wrong frame still fails.

Use whenever you write or review a test. A test that still passes after you delete the feature it covers is hollow. Run the five questions before accepting any test.

Use before finishing anything that depends on external state a person controls - a file, an asset, a record. Walk through what happens if they rename it, move it, delete it, or duplicate it.

Read once when starting work in a project that has the instincts plugin installed - explains that instincts is the reflex layer on top of superpowers and points to the individual instinct…

Use when about to assert any factual claim about what code or a product does - in an answer, a doc, a commit message, or anything a user will see. Confirm the claim against the primary source before stating it; never trust memory, the user's framing, plan headers, or doc tables on faith.