Describe the repeated task

Every automation starts with a task you already do by hand. Before you open Shortcuts or write a script, describe that task precisely. Most automations fail here, in the description, not in the code.

Pick one task you repeat. Write down six things about it:

• Trigger: what starts the work. A hotkey, a Finder selection, a schedule, a new file in a folder.
• Input: the exact data the task needs. File paths, text, a folder.
• Actions: the ordered steps, the way you’d explain them to a colleague.
• Output: what exists afterwards that did not exist before.
• Success check: the evidence that proves it worked.
• Failure boundary: what must never happen.

I call this a task card. Here is a real one:

trigger: I press a hotkey after taking a screenshot
input: the newest PNG on the Desktop
actions: rename to acme-2026-08-03.png, move to ~/Projects/acme/media
output: the renamed file in the media folder
success: file exists at the destination, Desktop copy is gone
never: overwrite an existing file, touch anything that is not a PNG

We’ll use this screenshot task as the running example for the whole course. By the end it runs from Finder and on a schedule.

Testable or not

Compare two descriptions of the same wish.

“When I finish a screenshot, rename it with the project and date, move it into the project media folder, then reveal the new file.” You can run this and check every claim.

“Organize my Mac.” No trigger, no defined input, no way to know when it succeeded. You can’t automate a sentence like that. You can only argue with it.

The failure boundary

The last line of the card deserves the most care. Write down what must never happen. Replacing an existing file. Touching a folder outside the project. Deleting anything.

The first time your automation meets unexpected input, that line is the difference between a harmless no-op and lost work. I’d rather have an automation that refuses to run than one that guesses.

Narrate it once

Before you build anything, do the task by hand one last time. Say every step out loud.

You’ll notice small decisions you make without thinking. You skip a file because it’s a draft. You pick a different name when one is already taken. You check the folder first.

Each of those decisions goes on the card as an explicit rule. If it doesn’t, it becomes a bug later, and you’ll rediscover it at the worst time.

Try this with your own task now. Fill in all six lines. If one line stays empty, you don’t know the task well enough to automate it yet.