AI Agent Workflow Collection

Resolve ambiguous requests by investigating, choosing the best-supported reading, and stating the interpretation — instead of guessing silently or blocking on questions. Use whenever a request has multiple plausible readings or an unstated parameter (which file, which env, how thorough, what format).

Treat any change to a public or shared interface — exported functions, HTTP endpoints, CLI flags, config formats, event/message schemas, DB schemas — as a contract change with consumers you can't see. Use before modifying anything other code depends on.

When recommending between options, match the strength of the claim to the strength of the evidence — commit when evidence is clear, say it's a coin flip when it is. Use whenever the user asks "which should I use", "what's the best way", "A or B?", or you're proposing a design choice.

Async/concurrent/streaming discipline — five questions (overlapping runs, check-then-act, mutation across await, response ordering, cancellation), idempotent retries, shared-state audit, race amplification. Use for async fan-out, streams/SSE, jobs, caches, or flaky timing-smell bugs.

Write scripts and file handling that survive the machine they didn't develop on — path separators, shell dialects, line endings, case-sensitivity, missing tools. Use when writing shell scripts, CI steps, path manipulation, file I/O, or install/setup instructions others will run.

Stop-and-check protocol before any destructive or hard-to-reverse operation — rm, overwrite, force-push, reset --hard, DROP, bulk delete, killing processes. Use the moment a planned action would destroy state that cannot be trivially recreated.

Adding/upgrading/removing dependencies — justification bar, changelog + pinned-constraint archaeology, matching package-manager/lockfile hygiene, one bump at a time, gates after. Use before touching package manifests, on security advisories, or version-mismatch errors.

Enumerate edge cases against a concrete checklist before declaring code complete. Use when implementing or reviewing any function, handler, parser, or data transformation — after the happy path works, before reporting done.

When something that should work doesn't, suspect the environment before rewriting the code — wrong directory, stale build, missing env var, version mismatch, dirty state. Use when a command fails unexpectedly, tests fail that "can't" fail, or behavior contradicts the code you're reading.

Write errors and log lines that name the failing thing, the offending value, and the likely fix — for the 3am reader. Use whenever writing a throw/raise, a log statement, a validation message, or a CLI/API error response.

When to ask the user versus decide — reversibility × blast-radius matrix, batched questions with recommendations attached, proceed-with-stated-assumption. Use when uncertain mid-task, tempted to ask "should I...?", or before destructive, outward-facing, or scope-changing actions.

Honest sizing and scope — probe before promising, surface 10x discoveries immediately (never silently absorb or shrink), vertical slices, calibrate finish quality to the ask. Use when sizing work, when scope balloons mid-task, or when a "quick fix" reveals architectural change.

When asked how something works or why, teach at the asker's level — grounded in their actual code, one runnable example, no jargon walls. Use for any explanatory question: "how does X work", "why does this happen", "what's the difference between", "walk me through".

When the user corrects you, fix the class of mistake everywhere it occurs — not just the flagged instance — and carry the rule forward. Use the moment a user points out an error, rejects an approach, or expresses a preference about how you work.

Live-system triage — read-only evidence first, establish what/since-when/how-wide, correlate onset with changes, trace one failing request, mitigate reversibly before root-causing. Use when production is broken now, or before restarting/redeploying/deleting as a first move.

Clean up your session's side effects — background processes, temp files, debug scaffolding, test data, stashed state — before reporting done. Use at the end of any task that spawned servers, wrote scratch files, added debug output, or altered state beyond the intended diff.

Code calling LLM APIs — model output is untrusted input: defensive parsing, server-side schema validation, authorization never from model output, approval-gated writes, injection awareness, cache-prefix economics, streaming edges. Use for agent loops, tool definitions, or prompt/model changes.

Handle numbers like they bite — float equality, currency arithmetic, rounding, division by zero, overflow, unit mismatches. Use when writing any arithmetic beyond a counter: money, percentages, averages, coordinates, durations, aggregations, or comparisons of computed values.

Catch the algorithmic and I/O performance classics before shipping — O(n2) on unbounded input, N+1 queries, sync calls in hot/async paths, unbounded memory. Use when writing loops over data of unknown size, database access in loops, or anything on a request path.

Distinguish "explain/assess this" from "change this" before acting. Use whenever a message could be read either as a question or as a change request — especially bug descriptions, "why does X happen", "what do you think of Y", and thinking-out-loud messages.

Systematic debugging — reproduce, bisect, prove the cause with a falsifiable hypothesis, fix minimally, re-verify against the original repro. Use for any bug, test failure, regression, or flaky behavior, before proposing a fix — and whenever a first fix didn't work.

Security checklists for everyday diffs — parameterize at trust boundaries, allowlist enums, per-object authorization, secrets never in logs/bundles/errors. Apply while writing any code touching user input, authn/authz, secrets, paths, URLs, subprocesses, SQL, HTML rendering, or external APIs.

Detect when you're iterating without converging — third failed attempt at the same problem — and force a zoom-out instead of a fourth variation. Use when consecutive fixes to the same failure haven't worked, when you're re-editing the same lines, or when each attempt is a guess rather than a deduction.

Delegate broad searches and independent subtasks to subagents to keep the main context clean. Use when a question requires sweeping many files or directories, when several independent investigations could run in parallel, or when raw tool output would flood the context you need for the real work.