Skip to content
SearchSubscribe
Expert · Lesson 01 — Retrofit — applying structure to a project that's already a mess
E01Expert
Expert · Lesson 01● live

Retrofit

Applying structure to a project that’s already a mess — without pausing shipping.

25 min read · several hours applysignature Expert lesson

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.

№ 01

The big-bang rewrite

claim looks like“"Let's just rebuild it correctly." Stop work, redesign, restructure for two weeks.”
what’s missingBy week 2 you've burned all velocity; the rebuild has its own bugs; the original project still doesn't work; team morale tanks. Most rebuilds fail because the work doesn't justify a 2-week pause.
the moveRetrofit incrementally. One piece at a time, each ~2 hours, while the project keeps shipping. The rule: never let retrofit work block today's ship.
№ 02

The complete-makeover trap

claim looks like“Try to install all 13 folders, all 5 agents, all 7 disciplines at once.”
what’s missingCognitive load is too high. You spend two days configuring instead of working. Half the structure goes unused because it doesn't fit your actual workflow yet.
the moveInstall ONE piece, use it for 7 days, then add the next. Order matters: CLAUDE.md first (immediate value), Sprint Contracts second (catches in-flight bugs), Postmortems third. Everything else after the first three earn their place.
№ 03

The structure-without-discipline

claim looks like“Folders created. Templates dropped in. Sprint contract written for one sprint. Then the discipline lapses; structure exists but isn't used.”
what’s missingFolders alone don't change behavior. Without consistent application, the retrofit is decorative. Six weeks later the project is back to where it started, plus some unused folders.
the movePick ONE discipline you'll apply to every piece of work for 30 days. Sprint Contracts is usually right — it shows up on every meaningful sprint. The 30-day commitment is what makes the structure stick. Pile on more after habit forms.

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.

The triage test
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.

Retrofitting a 5-month-old project

Six operator turns, six agent turns. Result: the 30-day plan, the branching at week 2, the rule that prevents stacking retrofit + refactor.

  1. 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?

  2. 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?

  3. operator

    I keep re-explaining the project to Claude every session. Stack, conventions, what we're working on. Same thing every time.

  4. 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.

  5. operator

    Week 2 — what's next?

  6. 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?

  7. operator

    Done-when-not-done. Bit me three times last sprint.

  8. 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.

  9. operator

    What if I want to retrofit while ALSO refactoring some bad code?

  10. 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

WeekInstallTimeSuccess metric
Week 1CLAUDE.md at project root (Foundations 01 skeleton)~30 minAgent’s first response in next session mentions specifics from the file without being asked
Week 2Sprint Contracts OR Postmortem Discipline (whichever matches your bigger pain)~30 min initial + 5 min per useUsed at least once in the week; the operator can name the value it produced
Week 3The OTHER discipline from week 2 — OR re-tune week 1-2 if not sticking~30 minBoth pieces are firing; operator has run the playbook on at least 2 sprints + 1 incident
Week 4Stabilize. Don’t add new structure. Audit what’s working.~60 min auditOperator 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

The triage → 30-day plan flow
Agent reports
"Done. Here's the status."
Apply the diagnostic
"Walk every claim. Test method?"
All claims have
observable test methods
Some claims marked
INCOMPLETE
Agent says it
cannot verify
Run the tests yourself.
Pass or revise.
Block on those criteria.
Re-plan around the gaps.
Revise the criterion or
run the tests yourself.
Big-bang rewrite vs incremental retrofit
"done"
Shape claim
Inherited assumption
Schema-quiet mismatch
"240 files saved at 2304×1296"
"Auto-labels look good per baseline"
"Labels uploaded successfully"
Did anyone open one?
Was the assumption re-verified?
Were the IDs actually right?
Need:
visual inspection step in contract
Need:
explicit re-validation of every inherited claim
Need:
cross-system schema check, not upload-success
The week-by-week decision tree
Sprint requested
Draft testable success criteria
Builder + Evaluator co-sign. Every row has a "How to test" cell.
Build against contract
Builder self-eval
runs each test method
Evaluator independent eval
fresh eyes, same tests
Ship
Return to Builder

Prompt kit

Three prompts for triage, planning, and auditing the retrofit. Save in your CLAUDE.md or a personal snippets file.

The triage test
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.
Plan a 30-day retrofit from scratch
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.
Audit a partial retrofit — is it sticking?
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.

0/5
  1. 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."
  2. 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.
  3. 03Week 1: install CLAUDE.md only. Use the Foundations 01 skeleton.30 minutes. Save at project root. Don't add anything else this week.
  4. 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.
  5. 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.
Expert tier · what's next

After this lesson