Article 1: No issue, no code

I keep a small set of personal rules pinned next to my keyboard. They aren't aphorisms. They're the operating rules I've decided govern any code I touch, whether I'm typing it myself or supervising an agent that's typing it for me. I call them my articles, and the first one is the shortest:

No issue, no code.

Every change starts with a tracked intent. Not a commit. Not a branch. An issue, with a title that says what's about to change and why, written down somewhere that survives the editor closing.

I had to write this rule down for myself before I'd live by it. The honest version of my own history is that I broke it constantly for the first decade of my career. Quick fix in the dashboard. Two-line tweak to the deploy script while I was in there. A "let me just" change to the Helm values that nobody asked for and nobody saw. The work shipped. The intent was lost the moment the editor closed.

This is the foundation piece for the rule. It's the cheapest discipline I know and it survives every shift in tooling.

Why the rule earns its keep

The cost of a change isn't the cost of typing it. The cost of a change is the cost of explaining it later, to the auditor, to the next engineer, to yourself in six months when something downstream breaks and you're trying to figure out what the original intent was.

When the change has a tracked issue, the explanation is free. You read the issue. You see the intent. You see who agreed it should ship. You see what was in scope and what wasn't. The commit message references the issue; the PR references the issue; the deploy log references the PR. The lineage is intact.

When the change doesn't have a tracked issue, the explanation has to be reconstructed. You read the diff. You guess at the intent. You ping the engineer (who has moved on, who is on PTO, who has forgotten). You read the Slack scrollback (which has aged out). You read the commit message (which says "fix"). The lineage is gone.

The cost asymmetry is real and large. Writing the issue takes thirty seconds. Reconstructing the intent later can take hours, and frequently doesn't succeed at all. The "quick fix" pattern shifts work from now-me to future-me without my consent.

What a useful issue looks like

The issues I write for myself are short. They aren't tickets in the project-manager sense. They're a one-paragraph artifact, title, intent, scope, and a place for the conversation to live if there is one.

A title that says what's about to happen, in present tense. Not "broken" or "fix needed." Closer to "tighten the egress policy on the inference namespace" or "swap the model-class enum for a labeled tier."

An intent paragraph. One sentence on what's being changed. One sentence on why. Past me writing for future me, and past me writing for an agent that needs to know what's actually being asked for.

A scope line. What this change is, and what it isn't. The "isn't" matters more than the "is". It's the line that protects the change from drifting into next-door work. "Tighten the egress policy. Not changing the network policy CRD. Not touching the service mesh."

A place for the conversation. Issue comments, PR description, a linked design doc, a Slack thread captured into the issue. Wherever the back-and-forth lives, it lives attached to the artifact, not floating loose in chat.

That's the whole shape. Four parts, two minutes to write, and the artifact survives.

What changes when an agent is doing the typing

I had to rewrite this rule in 2024 when I started letting agents do significant amounts of the typing for me. The rule didn't change. The reason it matters got sharper.

When I'm typing the code. I have the intent in my head whether or not I wrote it down. The risk of skipping the issue is mostly to future-me. Bad enough, but bounded.

When an agent is typing the code, the agent doesn't have the intent in its head. The agent has whatever is in its context window. If the issue isn't there, the intent isn't there, and the agent will do its honest best to guess the intent from the surrounding code, which is exactly the failure mode that produces "this looks right" changes that are wrong about the part that actually matters.

The fix is the same fix as before, just enforced harder: write the issue first, hand the issue to the agent, and require that the agent's output reference the issue. The issue becomes the contract. The agent's job is to satisfy the contract. The contract lives in a place that survives the agent session ending.

The other thing that gets sharper with agents is scope drift. A human doing a quick fix feels cultural pressure not to quietly rewrite five other files while they're in there. An agent doesn't. The scope line in the issue is what tells the agent (and the reviewer) what the agent was supposed to touch and what it wasn't. Without that line, the agent's "while I was in there" changes are indistinguishable from the legitimate ones, and you've lost the ability to review intent vs. what actually shipped.

I've started treating the issue as structured input the agent reads, not a thing-I-write-after-the-fact for the auditors. The order matters. Issue first. Then agent. Then PR. Then merge. Skip step one and the rest of the chain is operating on guessed intent, which is the same as no intent.

The objections, and what I do with them

The most common objection to this rule, which I've made to myself many times, is that it's overhead for trivial changes. Is the typo fix really worth a tracked issue? The honest answer is yes, and I've stopped pretending otherwise. The typo fix takes thirty seconds; the issue takes thirty seconds; the explanation cost saved is small but real. The asymmetry hasn't changed. What does change is that the rule is the rule, there's no judgment call about which changes are big enough to track. Every change is tracked. The judgment call is what I get rid of.

The second objection is that some intents emerge mid-coding. You start to fix one thing, you discover the real problem is different, and the issue you wrote first is now wrong. I've handled this by treating the issue as a living artifact, not a contract carved in stone. If the intent shifts, you update the issue, not the commit message. The artifact still tells the truth about what shipped. The artifact's edit history tells the truth about how the intent evolved. Both are findable.

The third objection is that this is just how good teams already work. Sure. The rule is for the moments when "good team" stops being enough, when you're solo, when you're tired, when the platform is on fire and you "just need to" tweak the YAML to keep the thing alive. Those are the moments the rule earns its keep. The discipline isn't the thing you do on your best days. It's the thing you don't skip on your worst.

What this rule pairs with

This is article one of a small set. The rest of the articles get their own pieces, fail-fast, double-check before destructive operations, scope discipline, separation of intent and what gets shipped. They all lean on this one. None of them work without a tracked artifact attached to every change. The issue is the spine; the other rules are the muscles that hang on it.

The rule pairs especially cleanly with Decisions as Code at the platform level. DaC asks the platform team to centralize the business decisions and project them everywhere. The articles ask the engineer (or the agent) to centralize the change intent and reference it everywhere. Same shape at a different scale: capture the decision once, refer to it from every consumer. The platform's decisions live in the standards repo. The change's decisions live in the issue.

Why this is article one

I picked this rule as article one for the same reason any constitution starts with the meta-rule. Every other rule assumes there's an artifact to attach the rule to. Fail-fast assumes there's a tracked attempt. Double-check assumes there's a tracked operation. Scope discipline assumes there's a tracked scope. The issue is the spine. Every other rule is muscle on the spine.

If you read no other article in this series, the first rule is the one that pays for itself the fastest. Thirty seconds to write the issue; hours saved on every audit; whole categories of agent failure modes prevented. The payoff is large and the cost is trivially small.

So: no issue, no code. Not the cleverest rule. The one I'd keep if I had to keep one.

, Sid