After @mattpocockuk grilled my workflow for doc rot, I rebuilt the whole thing

Ok, hear me out. Recently @mattpocockuk grilled me I'm causing doc rot with all the handoffs and MD files my skills are creating.

0:00 / 0:13

Now I've completely overhauled my production environment through his recent Workflow for AI Coding and I'm sharing it.

This is indeed the 10th time since I've started building with AI. I'm not a developer and hardly wrote code in my life. However, I am very technical though, and have been drawn to computers all my life. That's why I think this is the largest opportunity most of us have seen in our lives.

What I had before

I'd built a handoff system I was kind of proud of. At the end of every session I'd type /handoff four things would happen. The current state of the project would update. A new lesson, if I'd learned one, would get appended. The full session would get written down twice, once locally, once into my Obsidian vault. And the next time I opened Claude Code on that project, all of it would auto-load.

Cross-session memory. Continuity. I could come back two weeks later, type a project name, and Claude would know. Then I tweeted it.

The reply

Three minutes later:

I disagreed for about eight seconds with Matt.

Then I opened my "lessons learned" file. 144 kilobytes. Five months of accumulated wisdom, half of which was about features I'd already deleted, some of which contradicted itself, all of which the AI was dutifully reading back into context at the start of every session.

0:01 / 0:08

He was right. The code is the truth. Closed issues are the truth. Everything I'd ben writing was a prose paraphrase of truth, and paraphrases rot the moment the thing they paraphrase changes. So I woke up at 5am and tried to rebuild it like an engineer would.

Five things changed

1. The state file used to grow, while now it gets overwritten. Every session used to tack a new section onto the top. Three sessions in, the current state was buried under three layers of "previously...". Now it's a living overwrite. Max 1.5 KB. If you want to know what happened three sessions ago, you read the dated handoff.

2. The handoff files used to live forever. Now they have an expiry date. Each one carries a 30-day TTL in its header. A cron archives them when the window closes. The event log is immutable while it's relevant after which it goes to cold storage you can search but don't auto-load. I don't want to lose my precious history of development because one day it will be funny how I've been creating things. That day is not today.

3. The PRDs used to be the spec. Now they're throwaway. This one hurt. I love a good PRD. But the PRD's only job is to get you to the implementation issues. Once those issues close, the closed issue is the canonical record.

Every PRD I write now ends with a footer that says exactly that: throwaway, archive in 30 days, the issue is what matters.

4. The work used to come in horizontal layers.

Now it comes in vertical slices.

I used to break PRDs into "phase 1: database, phase 2: API, phase 3: UI." Easy for the AI. Brutal for me. You don't see anything actually working until phase 3. Now I break PRDs into thin slices that each cut through every layer at once. A slice is demoable on its own. This morning I broke one PRD into two issues, each a complete vertical, each independently grabbable by its own Claude session.

I suggest you take a look at Full Walkthrough: Workflow for AI Coding by Matt Pocock to understand more about how this works.

5. Every artifact now contains its own next step. This one isn't from Pocock. It's from me getting yelled at by my co-founder this afternoon. I'm not a developer. When I open a GitHub issue a week after I created it, "acceptance criteria" is useful but it doesn't tell me what to type into the terminal. So I added a rule: every issue, every PRD, every handoff, every brief I create from now on ends with a "what to do now" section. Concrete commands, where to run them, what to expect enforced in four places at once so I can't forget.

The flow is different now.

I describe a feature in plain English. Claude interviews me until the shape clicks, then writes a PRD as a GitHub issue. I run a command that breaks the PRD into vertical slices and creates them as issues, each with its dependencies wired up and a "what to do now" section at the bottom.

For each slice I open a fresh Claude Code session, free of context bloat from the previous slices, and start it on the issue. Claude writes the test first, makes it fail, writes the code, makes it pass, refactors. He opens a PR. I smoke test, merge, move on.

At the end of every session I run /handoff. The state file overwrites itself. The dated event log gets written, locally and in the vault. A small tool checks my memory layer for staleness and bloat and tells me when something's drifting. Less prose. More pointers. Everything reads back to code and closed issues.

What I haven't fixed yet

My Claude keeps suggesting I defer work to tomorrow. I have a memory file telling him not to. He did it three times today. I had to reinforce the memory mid-session. Rules degrade if you don't reinforce them.

Cross-project mirroring is still manual. Growth artifacts (X drafts, blog posts, briefs) live in each project's repo, and I copy them to my vault by hand. Next on the pile. I'm publishing this knowing the system isn't finished. That's kind of the point. It's a workflow, not a destination.

What I'd say to anyone using Claude Code

Use Github and do everything in pull requests. Do grill-me sessions. Don't paraphrase truth in a markdown file. The code is truth. I am learning the basics of software development. That's about it. Without it I'd be shipping slop for years.

If you're not a developer either, but you're as obsessed with what this tooling makes possible as I am, write the next step into every artifact you create. You'll thank yourself a week from now when you don't have to ask "wait, what was I doing here?"

Thanks @mattpocockuk for the shove.