
Retrofit
Applying structure to a project that’s already a mess — without pausing shipping.
Why retrofit beats rebuild
You have a project. It’s been running for months. There’s no CLAUDE.md. The agents (if you have any) are vaguely defined. Decisions live in chat history. Notes are scattered. Things break and get fixed without postmortems. The project ships, but the operating layer underneath it is invisible.
The instinct is to pause and rebuild. Stop work for two weeks, install everything correctly, then resume. Almost always wrong. 80% of rebuilds fail.The project loses velocity, the rebuild has its own bugs, morale tanks, the original work still isn’t shipping correctly. The pause didn’t justify itself.
The right shape is incremental retrofit while shipping continues. One piece at a time. ~2 hours each. The project keeps shipping the entire time.Three pieces in 30 days is realistic; that’s a 30-day plan that succeeds 80% of the time vs the rebuild’s 20%.
This lesson is the 30-day plan. The triage that picks the first piece. The discipline that makes the second piece earn its way in. The rule that prevents you from over-installing structure that doesn’t fit your work.
The five-month story
Five months into Quantum Caddy I had no CLAUDE.md, no sprint contracts, no postmortem template. Decisions were buried in chat. Agents were one-and-done. The project was shipping (slowly, with regular regressions) but the operating layer underneath it was invisible.
I tried the rebuild first. Two-day pause, drafted a vault structure, installed agents, wrote a CLAUDE.md for every venture. Day 3 I went back to actual work. By day 7 most of the structure was unused.I’d configured it cold without knowing which parts I’d actually use, and the new structure didn’t fit my workflows because I’d guessed at the workflows.
The pivot: retrofit one piece at a time, prove it sticks for 7 days, then add the next. CLAUDE.md week 1. Sprint Contracts week 2. Postmortem template week 3. By the end of the month I had three disciplines actually being used — not seven that existed but lay dormant.
The compound effect across months: those three early pieces produced the conditions where every subsequent retrofit (Memory architecture, Hooks, Vault structure, Wiki synthesis) had a place to fit. Big-bang rebuild would’ve produced none of that.
Three retrofit failures
The patterns that make retrofits fail. Hover any card to see the diagnosis.
The big-bang rewrite
The complete-makeover trap
The structure-without-discipline
The fix in all three: incremental, paced, with discipline. The structure doesn’t install itself — habit installs the structure.
The triage test
Before installing anything, run this diagnostic. Surfaces the actual pains and matches each to a specific retrofit move.
Walk this project and identify the THREE biggest operating pains:
1. What does the operator re-explain to Claude most often?
(CLAUDE.md candidate)
2. What kind of work fails most often despite "looking complete"?
(Sprint Contracts candidate)
3. What kind of incident has happened more than once?
(Postmortem Discipline candidate)
4. What knowledge is the operator clearly losing in chat history?
(Vault + Wiki Synthesis candidate)
5. What multi-step workflow is the operator manually walking 3+
times? (Skills candidate)
Output a sorted list of pain → retrofit move. Top three are the
30-day plan. Anything beyond top three is post-30-day work.
Don't recommend a complete makeover. Most retrofits fail because
they try too much at once.Surfaces top three pains. Match each to a retrofit move. Top three become the 30-day plan; rest is post-30-day.
The triage matters because the right retrofit move depends on what’s actually broken.Generic advice (\"start with vault structure\") fails when the operator’s actual pain is something else entirely. Match pain to move and the retrofit pays back; mismatch and the structure sits unused.
Annotated transcript
A real conversation: operator with a 5-month project, no operating-layer structure, asking where to start. Click any pinned annotation under an agent reply to expand the “why this turn matters” commentary.
Six operator turns, six agent turns. Result: the 30-day plan, the branching at week 2, the rule that prevents stacking retrofit + refactor.
- operator
I have a project that's been running for 5 months. No CLAUDE.md, no agents, no contracts. Notes scattered across Notion, GitHub issues, random markdown files. Decisions undocumented. Where do I even start?
- agent
First — DON'T pause shipping to retrofit. The instinct is "let's stop and clean up." Almost always wrong; the project loses momentum, the rebuild has its own bugs, and 80% of operators bail by day 5.
The right shape is incremental retrofit while shipping continues. Pick ONE piece, install it, use for a week, then add the next. Three pieces in 30 days is realistic and high-leverage.
What's the most painful thing about working on this project right now?
- operator
I keep re-explaining the project to Claude every session. Stack, conventions, what we're working on. Same thing every time.
- agent
That's CLAUDE.md territory. First retrofit move:
Day 1: Write CLAUDE.md. ~30 minutes. Stack, key terms, active work, three rules. Save at project root. Use the skeleton from Foundations 01.
Next session you start, the agent loads it automatically. The re-explanation problem disappears overnight. You'll know it worked when the agent's first response mentions specifics from your CLAUDE.md without being asked.
Don't add anything else this week. Use the new CLAUDE.md for 7 days. Notice what's still painful. THAT's your second retrofit move.
- operator
Week 2 — what's next?
- agent
After CLAUDE.md, the highest-leverage second piece is usually one of two:
Sprint Contracts if your second-biggest pain is "Claude says done when it isn't." Install: TEMPLATE.md from the bundle goes in
docs/sprint-contracts/. Use on every sprint that touches user-facing work. ~30 min the first time; ~5 min subsequent.Postmortem Discipline if your second-biggest pain is "the same kind of failure keeps happening." Install: TEMPLATE.md goes in
memory/postmortems/. Use after every incident worth learning from.Don't pick both at once. Pick the one that matches the bigger pain. Add the other in week 3 if the first is sticking.
Which pain is bigger — done-when-not-done, or recurring failures?
- operator
Done-when-not-done. Bit me three times last sprint.
- agent
Sprint Contracts then. Same pattern: install in week 2, use for one full sprint, evaluate in week 3.
By day 30 you'll have:
- Working CLAUDE.md (week 1)
- One full sprint that used a contract (week 2-3)
- A choice for week 4: postmortems if something broke; vault structure if you're hitting routing pain; agent.md if you keep wishing for a specialist.The big-bang rewrite would have you installing all of this on day 1. That fails 80% of the time. The 30-day incremental retrofit succeeds because each piece earns its place before the next is added.
- operator
What if I want to retrofit while ALSO refactoring some bad code?
- agent
The retrofit and the refactor are separate decisions. The retrofit is about how you operate; the refactor is about what you're shipping. They don't conflict — but if you stack them, you get rebuild fatigue.
My rule: retrofit the OPERATING layer first (CLAUDE.md, contracts, postmortems). Once that's stable for 30 days, the refactor decisions become much cleaner — because you have a contract format to scope the refactor, a postmortem template if it goes sideways, and a CLAUDE.md that captures the new conventions.
Refactoring without operating-layer retrofit = chaos. Retrofitting operating layer first, then refactoring = controlled.
The 30-day plan — three pieces, one rule
| Week | Install | Time | Success metric |
|---|---|---|---|
| Week 1 | CLAUDE.md at project root (Foundations 01 skeleton) | ~30 min | Agent’s first response in next session mentions specifics from the file without being asked |
| Week 2 | Sprint Contracts OR Postmortem Discipline (whichever matches your bigger pain) | ~30 min initial + 5 min per use | Used at least once in the week; the operator can name the value it produced |
| Week 3 | The OTHER discipline from week 2 — OR re-tune week 1-2 if not sticking | ~30 min | Both pieces are firing; operator has run the playbook on at least 2 sprints + 1 incident |
| Week 4 | Stabilize. Don’t add new structure. Audit what’s working. | ~60 min audit | Operator can articulate which pain each piece reduced and by how much |
The rule: never add a new piece if the previous piece isn’t being used.Adoption is the constraint, not configuration. Most retrofits stall because operators install new structure on top of unused structure — the new piece doesn’t fix the old non-adoption, and now there are two unused pieces.
After day 30, the operator has earned the right to add more (vault structure, agent.md files, hooks, skills). But the first 30 days are about three pieces and consistent use, not seven pieces and partial use.
Three diagrams
Prompt kit
Three prompts for triage, planning, and auditing the retrofit. Save in your CLAUDE.md or a personal snippets file.
Walk this project and identify the THREE biggest operating pains:
1. What does the operator re-explain to Claude most often?
(CLAUDE.md candidate)
2. What kind of work fails most often despite "looking complete"?
(Sprint Contracts candidate)
3. What kind of incident has happened more than once?
(Postmortem Discipline candidate)
4. What knowledge is the operator clearly losing in chat history?
(Vault + Wiki Synthesis candidate)
5. What multi-step workflow is the operator manually walking 3+
times? (Skills candidate)
Output a sorted list of pain → retrofit move. Top three are the
30-day plan. Anything beyond top three is post-30-day work.
Don't recommend a complete makeover. Most retrofits fail because
they try too much at once.I have a project at <path> that's been running for <N>
months without operating-layer structure. I want to retrofit
incrementally over 30 days without pausing shipping.
Walk through:
1. Apply the triage test — what are the top 3 pains?
2. Match each pain to a retrofit piece (CLAUDE.md, Sprint
Contracts, Postmortems, Vault, Skills, Agents).
3. Sequence the pieces — CLAUDE.md week 1, then which week 2,
which week 3.
4. For each week, give me:
- The single piece to install
- The skeleton to start from
- The success metric (how do I know it's working?)
- The decision rule for week +1 (what determines what comes
next?)
Don't recommend installing more than 3 pieces in 30 days. Anything
beyond is rebuild territory.I started retrofitting <project> <N> weeks ago. I installed
<piece>. Walk:
1. Is the piece actually being used? (Count times it fired in
recent sessions.)
2. If used, is it producing the predicted value? (Is the original
pain reduced?)
3. If not used, why not? (Trigger words wrong? Workflow doesn't
match? Operator forgot it exists?)
4. Recommendation: keep using and add next piece, or fix this
piece before adding more?
Don't add new pieces if the previous one isn't sticking. Fix
adoption first; expand structure second.Apply this — start your retrofit
30-day exercise.Pick a real project. Run triage. Install one piece per week. Don’t skip the audit at week 4.
Run a 30-day retrofit on a real project
Each step takes 30-60 minutes spread across 30 days. Progress saves automatically.
- 01Pick ONE existing project that doesn't have operating-layer structure.Even partial structure (just a CLAUDE.md, no contracts, no postmortems) counts as "to retrofit."
- 02Apply the triage test. Identify your top 3 pains.Be honest. The pain you describe out loud is sometimes the symptom, not the cause. Talk to Claude — agent will help triage.
- 03Week 1: install CLAUDE.md only. Use the Foundations 01 skeleton.30 minutes. Save at project root. Don't add anything else this week.
- 04Week 2: install the second piece based on your #1 remaining pain.Sprint Contracts (done-when-not-done) or Postmortem Discipline (recurring failures) are usual. Use for 7 days; evaluate.
- 05Week 3-4: install the third piece OR re-tune the first two if they're not sticking.Most retrofits stall because operators add new pieces while the previous ones aren't being used. Fix adoption before expanding.