yw-workflow

Explain a topic like the reader knows nothing about it, as an HTML artifact with big pictures and few words. Use when the user asks to "eli5", "explain like I'm 5", or wants a dead-simple visual explainer instead of a text answer. Requires the Artifact tool; without it use eli5-text. Prefer this over eli5-text when the explanation will be re-read, shared, or kept.

Explain a topic like the reader knows nothing about it, in the conversation, with no artifact and no page to open. Use when the user asks to "eli5 this", "explain it simply", "what does this actually mean", or wants the plain version right now rather than a link. Prefer this over eli5 when the answer is needed mid-task, and when a bare "eli5 X" or "explain like I'm 5" could go either way.

Dispatch an independent adversarial reviewer that did not write the code, in an isolated git worktree, to try to break a change rather than agree with it. Use before merging anything non-trivial, when asked for "a fresh eye", "a second opinion", "review this properly", "try to break this", or when you have just finished work and are about to call it done. Also use on the FIX for a previous review, because that is where the next defect usually is.

Run concurrent agents in isolated git worktrees without them colliding. Use before starting multi-file work in a repo where another agent may be active, when asked to "run these in parallel", "spin up lanes", "use worktrees", when dispatching a reviewer, or when about to git checkout/pull/stash in a repo you did not just create. Also covers where built deliverables live and how lanes merge back to trunk.

Interrogate a plan, decision, or idea one decision at a time until the shared understanding is real. Use when the user says "grill me", "stress-test this", "poke holes in it", "am I missing anything", or before committing to any plan whose cost is more than an hour. Also use when a request is ambiguous enough that two readings would produce different work.

Keep a repo's docs/HANDOFF.md in the one shape that lets a fresh session start from the file alone, with a Start here block on top and dated sections appended as work happens. Use when asked for "a handoff", "/handoff", "write the handoff", "update the handoff", at the close of a session, or when the handoff-freshness hook warns HANDOFF STALE or HANDOFF SHAPE.

Set up CI, pre-commit hooks, a PR template, and GitHub branch protection for a repo, so its review gate holds where the work runs rather than only on one laptop. Use when the user asks to "set up CI", "add branch protection", "bootstrap this repo", "add git hygiene", "harden this repo's git workflow", or when starting real work in a repo that has none of this yet.

Prove a repo's self-checks can fail, by applying recorded two-line breakages to each script and requiring its own check to catch them. Use when a review finds an assertion that could not fail, when a ticket names a rule as one that must be provable by mutation, when adopting the gate in a new repo ("add the mutation gate", "mutation test the scripts"), or when deciding whether a proposed gate entry has earned its place.

Show only what is actually waiting on the human, delivered as clickable questions they answer in seconds. Use when the user asks "what needs me", "am I blocking anything", "/need-me", "what's waiting on me", at any natural pause where they may walk away, and before a handoff so the next session does not inherit a hidden queue of unanswered questions.

Run work as a closing loop instead of a trailing-off one. Ticket, branch, implement test-first, dispatch an independent review, fix what blocks, file what does not, and repeat until a review round comes back clean. Use when asked to "run the loop", "keep going until it's right", "loop until the feedback is perfect", "babysit this to done", or when handed a backlog of tickets to work through. Also use to decide what happens to review findings.

Chart a body of work too big for one session as a map of decision tickets on GitHub Issues, then resolve them one at a time until the route is clear. Use for a loose idea, a migration, a new project, or any effort where the destination is known and the way there is not. Triggers include "where do I even start", "this is too big", "chart this", "wayfinder".