Stop and ask me
Runbooks that finally get read, and installing doubt in something whose default setting is finishing.
We’ve got three skills at work for Shopify client repos, and between them they cover the entire life of one. shopify-onboard makes a new repo from the template and gets it talking to the store. shopify-template-sync takes a repo that already follows the workflow but has fallen behind, and drags it forward. shopify-workflow-upgrade is for the genuinely old stuff: a project that’s been sitting on Bitbucket on a branch called master since before we did any of this, that needs to be moved and renamed and rewired before it can even be called behind.
Each one is a single Markdown file with about eight lines of front matter on top. I want to say that plainly because “skill” oversells it a little. There’s no code. It’s a runbook, and if you handed it to a new hire instead of to Claude, it would work about as well.
And the steps in them are boring. Genuinely, completely boring. gh repo create --template, set the store in the toml, set three secrets, pull the live theme, commit, push, run /init. I could produce most of that from memory on a decent morning. If that were all the file contained I don’t think it would earn the disk space, and I’d probably have deleted it by now out of embarrassment.
What earns its place is the other stuff. The stuff you only know because you were wrong about it once, in a specific way, on a specific afternoon. And having now written three of these, I think that stuff comes in exactly two flavors.
The first flavor is facts that look like redundancy and aren’t.
The store URL lives in shopify.theme.toml. That was the whole point of a migration I did a while back, getting it out of package.json so that file could be byte-identical everywhere. Great. So why does every one of these repos also carry a SHOPIFY_STORE_URL GitHub secret with the same value in it?
Because CI never reads the toml on the live path. It reads SHOPIFY_FLAG_STORE off the secret. So the store does live in two places, deliberately, and if you’ve just spent a week de-duplicating config you will look at that and feel a very strong urge to fix it. You’d be fixing it into a broken deploy. So the skill just says so, out loud, in a blockquote, in all three files, every time. It’s not clever. It’s a note to a future person who is about to be very confident.
There’s a smaller one in the same family that I like more than it deserves:
The second flavor is the one I actually think matters, and it’s the places where the runbook is told to stop.
Here’s the one that taught me. All three skills do their work on a branch with the same name, feature/shopify-workflow-upgrade, which is nice and consistent and also a small trap, because a sync running a year after an upgrade walks straight into a branch of that name that already exists. git checkout -b errors out. And a thing executing a checklist, on hitting an error, will look for the way around the error, because getting to step 9 is what success looks like from inside step 1. git branch -D is sitting right there, one word away, and it is a completely reasonable next move if your only goal is to have a branch.
So the skill doesn’t say “make the branch.” It says find out what you’d be destroying first:
git branch --list feature/shopify-workflow-upgrade
git ls-remote --heads origin feature/shopify-workflow-upgrade
git log --oneline origin/main..feature/shopify-workflow-upgrade
gh pr list --head feature/shopify-workflow-upgrade --state openThen it forks. Fully merged into main, no unique commits, no open PR? It’s debris, delete it, nothing is lost. Unmerged commits or an open PR? Stop. Surface it to the person and let them decide, because those are three different decisions (reuse it, close the old PR, branch under another name) and none of them belong to a script.
That instruction is the most important line in the file and it’s also the only line in the file that doesn’t make anything happen. Everything else creates, copies, sets, commits. That one just stands there.
Which I think is the general shape of it. A model handed a numbered list will finish the numbered list. You don’t have to ask for diligence, you get diligence for free, sometimes more of it than you wanted. What you have to ask for, explicitly, occasionally in caps like a lunatic, is the doubt. Never auto-merge, leave the PR for the user. Don’t commit automatically, leave the changes staged for review. Run one project at a time, don’t batch-sync three repos in a single pass because it’s the same six commands. None of those are hard to follow. They’re just hard to think to write down, because nothing about the experience of working through a checklist suggests that the correct move might be to put the pen down halfway.
And the amount of doubt isn’t constant either, which surprised me a bit when I noticed it. shopify-onboard commits and pushes to main on its own without asking anybody. shopify-workflow-upgrade says, in bold, do not commit automatically. Same author, same week, opposite instruction. But onboarding happens in a repo that is four minutes old whose entire contents just came down off the store, so the worst case is you delete the folder and run it again, whereas an upgrade has you standing inside somebody’s actual project with years of history under your feet. Trust isn’t a setting you pick once. It’s a function of what’s waiting on the other side of being wrong.
The obvious objection here, and I want to give it its due because I made it to myself for about a month, is that this is just documentation wearing a costume. Write a README. Congratulations, you have invented the README.
And, sure, kind of. Except the failure mode of a README is that it loses to whoever’s in a hurry, and whoever’s in a hurry is always me. I did write the README version of this. It was accurate. I stopped opening it after the third project, because by then I remembered most of it, and “most of it” is precisely the shape of the problem: I remembered the steps, which were never the point, and forgot the store URL thing, which was. The difference isn’t that the skill is better written. It’s that it gets read start to finish on every single run by something that has never done this before and has no ego about re-reading step 3.
Okay, and one thing I should own, because I noticed it while writing this and it made me wince. That SHOPIFY_STORE_URL warning I was so pleased about? It’s copy-pasted, near verbatim, into all three files. Which is exactly the drift I built the template to kill, faithfully recreated one floor up in the documentation. If CI ever changes how it reads the store, I have three files to update and I will remember two of them. I don’t have a fix. Maybe a shared reference the skills all point at, maybe that’s over-engineering three Markdown files. Filing it under known and slightly embarrassing.
Anyway. If you’re writing one of these, the only real suggestion I’ve got is to draft the happy path fast and without much care, because the happy path is the part you’d have gotten right anyway. Then go back through it step by step and ask, at every single one, what happens if this is already done, or already exists, or is halfway done in a way I can’t see from here. The answers to that are the actual file. Everything else is typing.
Three Markdown files and one platform is the whole of my evidence here. But the question travels further than the files do.