Skip to content

Coding workflow guardrails: when to pause and ask better questions

A set of self-prompts for safer coding: map callers before edits, pin success before implementation, trace weird behavior to its origin, and explain the semantic diff before shipping.

tools workflow debugging testing review judgment 2026-04-23

These are not magic commands. They are decision prompts to run on yourself at the right moment so you stop making fast local edits that ignore blast radius, hidden contracts, or shipping risk.

The point is not ceremony. The point is to interrupt the exact failure mode that is most likely right now.

The core guardrails

/scout

Use when you are about to edit existing code, especially shared code.

Run it when:

  • touching a helper used in more than one place
  • changing a route, template, or factory boot path
  • renaming a function, field, or template context key
  • changing a query helper, serializer, or model shape

Ask yourself:

Who calls this, and what else breaks if I am wrong?

Minimum output:

  • code callers
  • template consumers
  • tests that pin the current behavior
  • likely blast radius

/spec

Use when you know what you want, but success is still vague.

Run it when:

  • fixing a bug with fuzzy reproduction
  • starting a non-trivial feature
  • changing behavior that needs acceptance criteria
  • feeling tempted to "just start coding"

Ask yourself:

What failing test, probe, or acceptance check would prove this is not done yet?

Minimum output:

  • acceptance criteria
  • smallest failing test or probe
  • stop-and-ask questions if the contract is still unclear

/trace

Use when behavior looks wrong, strange, or legacy-heavy.

Run it when:

  • a weird branch looks deletable
  • an old guard clause seems unnecessary
  • data is being transformed in a non-obvious way
  • the bug lives in code you do not understand yet

Ask yourself:

Why was this written, and what constraint was it serving?

Minimum output:

  • blamed line or function
  • introducing commit or surrounding history
  • related tests
  • best guess at original intent

/why

Use after implementation but before commit, handoff, closeout, or deploy.

Run it when:

  • the code now "works"
  • the diff is larger than it felt while editing
  • you are about to hand work to another agent or to future you
  • you want to know whether this should ship, not just whether it runs

Ask yourself:

What changed semantically, not just textually?

Minimum output:

  • what behavior changed
  • what might break
  • load-bearing assumptions
  • what would make the diff unsafe to ship

The contract and scope guardrails

/contract

Use when you are changing what another surface expects.

Run it when:

  • changing request or response shapes
  • changing template context keys
  • changing form fields or validation behavior
  • changing env vars, CLI flags, or config assumptions
  • changing DB write semantics

Ask yourself:

What depended on the old contract, and is this still backward compatible?

/slice

Use when the task is starting to sprawl.

Run it when:

  • you have too many files open
  • you are mixing bug fix, refactor, cleanup, and feature work
  • the ticket keeps growing while you work
  • you are no longer sure what the smallest honest ship is

Ask yourself:

What is the smallest version I can ship without lying to myself?

/shipcheck

Use when the work may stop being private code and become reality.

Run it when:

  • the change affects deploy/runtime behavior
  • touching auth, admin, migrations, jobs, email, or public routes
  • changing setup truth or operating assumptions
  • the change probably needs post-deploy probes

Ask yourself:

What proves this is safe beyond my editor?

Minimum output:

  • tests run
  • live probes needed
  • rollback surface
  • docs or state files that may now be stale

Quick self-cue map

  • "I am about to edit existing code." -> /scout
  • "I have not pinned success yet." -> /spec
  • "This weird code probably has history." -> /trace
  • "I changed an interface or expectation." -> /contract
  • "This task is getting too big." -> /slice
  • "I think I am done." -> /why
  • "This may ship or affect reality." -> /shipcheck

Simple operating loop

  1. Before editing existing code, run /scout.
  2. Before non-trivial implementation, run /spec.
  3. If the bug or legacy behavior is weird, run /trace.
  4. If you changed an interface, run /contract.
  5. If scope is drifting, run /slice.
  6. Before commit, handoff, or closeout, run /why.
  7. Before deploy-affecting work leaves the branch, run /shipcheck.

If you only adopt two of these, start with /scout and /why. They give the biggest improvement fastest because they attack the most common mistake: changing the right line without understanding the surrounding contract.