edit-discipline

Edit Discipline

This rule comes from app/rules/edit-discipline.md in ai-toolkit. It applies to every task in this workspace, not only when it is loaded.

Edit Discipline & Reviewable Changes

Edit files with the editing tools, not the shell

Use the edit and write tools to change a file. Do not rewrite tracked files through bash with sed, awk, tee, a heredoc, or > redirection.

This is not a style preference. A shell rewrite is opaque to the host: the session records a command, not a change. An edit call records which file changed and how, so the interface can render it, a reviewer can read it, and a later turn can cite it. A sed line records none of that, and the only way to find out what happened is to read the file again.

The shell remains correct for what it is for: running builds, tests, linters, git, package managers, and generators that own their own output.

Show the change before calling the work done

Before reporting a file-changing task as finished, show what changed:

git diff -- <paths>          # tracked files
git status --short           # what is new or removed

Paste the diff into the reply, or state precisely why it is too large and summarise it by file with the counts. A task that reports success without showing the change asks the reader to take the result on trust, and the reader is the one who has to decide whether to commit it.

For an untracked file, show the content you wrote, not a description of it.

Why both halves matter together

Editing through the tools makes a change recordable; showing the diff makes it reviewed. Either alone leaves the person deciding whether to ship blind to something they are accountable for.