# AI coding workflow checklist

One page for working with a coding agent. It works with any agent that can
read your repository and run commands. Skip a box only on purpose.

## 1. Before you prompt

- [ ] I can state the goal in one sentence.
- [ ] I know the acceptance check: the test, command or screen that proves it
      is done.
- [ ] I know which files are involved, or I will ask the agent to find them
      first.
- [ ] The working tree is clean, so the agent's changes are easy to see and
      easy to undo.

## 2. Give context

- [ ] I point at files by path instead of describing them.
- [ ] I state the constraints: no new libraries, follow this pattern, keep
      this interface.
- [ ] I say what not to touch.
- [ ] I paste the real error, log or screenshot, not my summary of it.
- [ ] I give what the code cannot tell: a decision, a deadline, a rule of the
      business.

## 3. Plan first

- [ ] For anything non-trivial, I ask for a plan before any code.
- [ ] The plan lists the files it will change and how each step is verified.
- [ ] The agent lists its assumptions and the decisions it needs from me.
- [ ] I answer those questions. I do not let it guess.
- [ ] If the plan is wrong, I fix the plan, not the code that comes after.

## 4. Work in small steps

- [ ] One logical change at a time.
- [ ] The agent runs the tests or the build after each step.
- [ ] I read the diff of every step before the next one starts.
- [ ] I stop it the moment it drifts, and I restate the goal.
- [ ] After two failed corrections, I start a fresh session with a better
      prompt.

## 5. Verify

- [ ] I ask for evidence: the command that ran and its output.
- [ ] I never accept "it works" without that output.
- [ ] I run it myself at least once: the tests, the build, the real screen.
- [ ] For a bug, the failure is reproduced first, and the cause is stated
      with evidence before any fix.
- [ ] After the fix, the same reproduction runs again and passes.
- [ ] The diff contains nothing I did not ask for.

## 6. Finish

- [ ] One commit per logical unit, with a message that says what and why.
- [ ] The reproduction is kept as a regression test where practical.
- [ ] I write down what was learned: the gotcha, the decision, the command.
- [ ] I update the instructions file the agent reads, so the next session
      starts with it.
- [ ] Temporary logging and scratch files are removed.

## When it goes wrong

- The agent built something else: the goal or the context was missing. Go
  back to sections 1 and 2.
- It says done but it is not: it had no check to run. Go back to section 5.
- It keeps making the same mistake: write the rule into the instructions
  file, or enforce it with a script.
