Finish the automation runbook

Time to finish the screenshot sorter. It accepts selected screenshots, creates safe project copies, and runs either from Finder or from a LaunchAgent.

Every module gave it a piece. The task card. The contract. The Shortcut trigger. The script. The plist. The lock. The log line. What’s left is proving the whole thing works, and writing down how to run it.

Test what will really happen

Test these cases against the finished automation:

• valid input
• duplicates
• filenames with spaces
• missing files
• denied permission
• two runs at the same time
• interruption before the final move

Each one replays a lesson from this course. And each has a defined correct answer, because you wrote the contract. Duplicates skip. Denied permission fails loudly. An interrupted run leaves no partial file behind.

Keep the fixtures and the expected results next to the script:

fixtures/
  one-file/    sample.png           -> expect: 1 copy created
  duplicate/   sample.png, run x2   -> expect: "already processed"
  spaces/      Screen Shot 3.png    -> expect: 1 copy, name intact
  wrong-type/  notes.txt            -> expect: rejected at input

Kept fixtures turn “I tested it once in August” into a suite you rerun after every macOS update and every edit to the script. That takes two minutes and catches the regression before the schedule does.

Write the runbook

A runbook is the page someone reads when the automation misbehaves. Document prerequisites, permissions, configuration, logs, dry run, manual run, scheduled run, how to pause it, how to remove it, and how to recover.

That sounds like a lot. In practice it’s one short line each:

permissions: Terminal -> Automation -> Finder (approved 2026-08-03)
logs:        ~/Library/Logs/screenshot-sorter.log
dry run:     ~/bin/sort-screenshots --dry-run
manual run:  ~/bin/sort-screenshots
disable:     launchctl bootout gui/$UID/com.flaviocopes.screenshot-sorter
recovery:    remove ~/.local/state/screenshot-sorter.lock if the pid is dead

The measure of done

Another person should be able to stop it safely. Not use it. Stop it, at two in the morning, without calling you.

If the disable line works when pasted by someone who has never seen the project, the runbook is real. If they have to ask you which domain, or where the plist lives, it isn’t finished.

Verify the runbook like code

Follow it literally. On a clean user account, or right after a reboot. Every step you perform from memory instead of from the page is a step missing from the page.

I do this once for every automation I keep. It’s boring. It’s also the only reason I can leave them alone for months.

Try this on your own sorter: hand the runbook to someone else, or to yourself after a reboot, and see if they can install it, run the dry run, and remove it without asking a question.