PAI Upgrade Woes

[mrutallie]

I’ve been using PAI since v2.0, and with every upgrade I end up spending a significant amount of time troubleshooting after following the documented upgrade path. Even when the upgrade completes successfully, I have to go back and forth with PAI to correct issues. Then over the next couple of weeks, I continue discovering items that didn’t migrate correctly or aren’t functioning as expected.

It’s getting progressively more time-consuming with each version.

I keep all customizations in /USER, but even those don’t seem to be cleanly recognized after an upgrade. I’m trying to determine whether this is something I’m doing incorrectly or if there’s a more reliable upgrade strategy I should be following.

For those who have a smoother experience:

• What does your upgrade process look like end-to-end?
• Are you doing anything beyond the documented steps (diff checks, clean installs, config validation, etc.)?
• How are you validating that customizations in /USER are being preserved correctly?
• Do you treat upgrades as rebuilds rather than in-place transitions?

Looking for a more disciplined, predictable approach because the current cycle isn’t sustainable.

[jlacour-git]

We went through a similar experience upgrading to 3.0 — not as rough as yours, but definitely not just "run the script and done." What helped was treating it as a three-phase process:

1. Pre-upgrade inventory

Before touching anything, we cataloged every local modification. Anything in /USER is safe by design — the installer doesn't touch those. The real risk is SYSTEM-tier files you've modified: hooks, handlers, generated files like SKILL.md.

We created a LOCAL_PATCHES.md file tracking each modification with the file path, what it fixes, and the linked upstream issue. Sounds like overhead, but it takes 10 minutes and saves hours of "wait, why did this break?"

2. Standard upgrade + reconciliation

We used the documented cp -r + install.sh path. After it ran, we went through LOCAL_PATCHES.md and re-applied each active patch. Two of our patches turned out to be upstream already in v3.0 — those we retired. The rest got re-applied.

Generated files need rebuilding after upgrade. SKILL.md in particular — it's built from Components + Algorithm + settings.json. If you don't rebuild, your identity, voice, and custom settings revert to defaults. bun Tools/RebuildPAI.ts handles this.

3. Validation checklist

After upgrade we verified: voice notifications working, identity correct in SKILL.md, statusline displaying counts, hooks firing. Caught two issues this way that we would have discovered days later otherwise.

What we'd add to the documented procedure:

• Back up settings.json before upgrade (the installer merges, but belt and suspenders)
• Keep a local patch registry if you've modified any SYSTEM files
• Always rebuild SKILL.md after upgrade
• Run a quick smoke test: voice curl, check identity, verify hooks

Not a perfect process — we still hit issues with voice IDs and hook compatibility. But the inventory step alone eliminated the "discovering broken things weeks later" problem.

For context: we filed issue #650 proposing upstream support for local patch tracking, and we have a SystemFileGuard hook (PR #727) that warns before accidentally overwriting patched files. Both awaiting review.

[mrutallie]

Thanks for the detailed explaination.

I've tried to do something similar by asking it to put any modifications into a file names something like POST_UPGRADE_TASKS.md but it seems to not always follow the procedure while creating any modifications. How do you have it consistently log any changes to that LOCAL_PATCHES.md file?

[jlacour-git]

The inconsistency is almost certainly in how the rule is written, not in the concept.

Instructions buried in a file like "log changes to POST_UPGRADE_TASKS.md" get skipped constantly. The LLM reads it once, acknowledges it, then ignores it under any time pressure.

Two things make ours reliable:

1. A hook at the tool level

SystemFileGuard.hook.ts fires as a PreToolUse hook before any Edit or Write to a SYSTEM-tier file. It reads LOCAL_PATCHES.md, extracts tracked file paths, and if the target matches — it asks the user to confirm. This does not replace logging, but it prevents the model from silently overwriting a patched file without surfacing the issue. Hook-level enforcement is harder to skip than file-based instructions.

2. A steering rule with a specific trigger, not a vague instruction

In USER/AISTEERINGRULES.md (which loads every session), the rule has three components that matter:

• A trigger: "For SYSTEM-PATCH proposals that are approved, add to LOCAL_PATCHES.md with all required fields."
• A bad example: "Apply a SYSTEM patch without adding it to LOCAL_PATCHES.md."
• A correct example: "On approval, apply fix, add entry with all fields, file upstream issue, link issue number."

The bad/correct contrast carries the weight. "Always log changes" gets ignored. "Apply without logging = bad, here is exactly what correct looks like" creates a much stronger behavioral anchor.

For your POST_UPGRADE_TASKS.md — rewrite the rule to be explicit about the trigger, required fields, and add a concrete bad example. That closes most of the gap.

On USER files not being recognized after upgrade — the most direct cause is usually SKILL.md not being rebuilt. SKILL.md is generated from your components and settings.json. If it is stale, it carries the wrong references and your USER customizations effectively do not exist from the model's perspective. Running bun Tools/RebuildPAI.ts after every upgrade is the single step most likely to fix that specific symptom.

[mrutallie]

Wow, that was very helpful. I'm going to try to integrate that into mine and hope for the best. I wish there was somewhere that consolidated best practices around daily usage of PAI, including things like this and other caveats. @danielmiessler wrote good documentation on the big picture, but a tactical how-to guide that consolidates what people have found to work best would be great. I know the discussion forum as a lot of that, but it's not a best practice guide which would simplify things greatly.

Again, thanks for this information. I'm sure it will help.

[mrutallie]

I just had a great conversation with another PAI user and he is using and older version (2.1) of PAI and has been customizing it to the hilt and has gotten some amazing results from it. He hasn't upgraded to anything newer and doesn't plan to. It dawned on me that I'm spending most of my time with AI to manage the implementation of PAI, only getting little real value out of it besides learning more about AI.

I'm curious if many others take this path as well, to grab a version of PAI and just stick with it regardless of what other upgrades come down the path. This is knowing that you don't have the latest and greatest from Daniel, but you are able to build a more stable system over time. Thoughts?

[Spirotot]

I'm curious if many others take this path as well, to grab a version of PAI and just stick with it regardless of what other upgrades come down the path. This is knowing that you don't have the latest and greatest from Daniel, but you are able to build a more stable system over time. Thoughts?

I'm considering doubling down on this kind of idea...

I already have forks of PAI with some of my own fixes/changes/improvements/cherry-picks. I'm getting really antsy for memory and efficiency improvements with PAI. Thinking I might start implementing myself (and/or borrowing from the existing PRs). I'd aim to keep strong separation between 'user' and 'system' data in case I want to merge in PAI updates in the future. Even so, I expect such merges may be AI-assisted semantic merges, or cherry-picks... so maintaining 'smooth git merge-conflict-free' upgrade paths doesn't even seem essential to me.

No doubt we'll continue to have shared infra & APIs for all kinds of things going forward (I mean the internet and websites aren't going to disappear imminently), but my feeling is that AI is going to cause every individual's personal computing setup to become almost entirely bespoke, full of novel custom functionality as well as a unique mix of components cherry-picked from others (<-- and all of this is in addition to the more raw 'memory' systems which are simultaneously coming to be via not just 3P frameworks like PAI but also native implementations in Claude proper).

[jlacour-git]

I try to keep up with Daniel‘s work, because I believe he is really giving us a great approach and constantly improving.

But of course, I make modifications and augmentations that suit my life. So far, it seems quite stable to keep both paths evolving.

Also, I think when I take a gift like PAI, and I change or add to it, I think I have an obligation to give back and share.

Because this „… full of novel custom functionality as well as a unique mix of components cherry-picked from others…“ will not work well if we all just take.

[Spirotot]

Because this „… full of novel custom functionality as well as a unique mix of components cherry-picked from others…“ will not work well if we all just take.
obligation to give back and share

Definitely interesting to think about, thanks for raising these points. BTW maybe this is just semantics -- I am not rooting for a world in which everyone is in their own silo. But I do actually think there could be a viable future where many people kinda do "only take" in a sense -- provided there are social networks like this (GitHub) where people can publish their setups (and that is a "give"). For example, even if I never submit another PR back to PAI, but I do publish my fork.. folks (including the author of PAI) could still use my fork or cherry-pick from it... but it becomes them "taking" back from me rather than me "giving" to PAI.

A related thought I've had lately: with AI writing [often good] code for people (even people who traditionally haven't written code), I wonder if there is a risk of projects becoming overwhelmed with the volume of PRs/'improvements' -- not even because the submissions are 'AI Slop' necessarily, but perhaps simply due to sheer volume of PRs... or, because the project becomes a cumbersome tangle of bespoke features/functionality (if the maintainers aren't sufficiently principled with what they accept).

[colin477]

Hi! I’m relatively new to PAI, but have been working in it non-stop. I have found is extremely useful. Specifically his algorithm and how it processes prompts…leads to more impactful output and for me a much more productive experience. I am focused on stability but have done a fair additions. From incorporating telegram chat, to read access for my email. I’m also trying to integrate better calendar management. All to say it’s been functioning well and my intention is to upgrade along the way.

…

On Fri, Feb 27, 2026 at 12:31 PM mrutallie ***@***.***> wrote: I just had a great conversation with another PAI user and he is using and older version (2.1) of PAI and has been customizing it to the hilt and has gotten some amazing results from it. He hasn't upgraded to anything newer and doesn't plan to. It dawned on me that I'm spending most of my time with AI to manage the implementation of PAI, only getting little real value out of it besides learning more about AI. I'm curious if many others take this path as well, to grab a version of PAI and just stick with it regardless of what other upgrades come down the path. This is knowing that you don't have the latest and greatest from Daniel, but you are able to build a more stable system over time. Thoughts? — Reply to this email directly, view it on GitHub <#754 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BWRIT7BPNEL7P6OA7SG6SC34OCLQFAVCNFSM6AAAAACV3QNHPCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKOJVGA2DGMI> . You are receiving this because you are subscribed to this thread.Message ID: <danielmiessler/Personal_AI_Infrastructure/repo-discussions/754/comments/15950431 @github.com>

[jlacour-git]

Hey, that sounds great! Will you be sharing your additions with us?

[jarednwilson]

I’ve been using PAI since v2.0, and with every upgrade I end up spending a significant amount of time troubleshooting after following the documented upgrade path. Even when the upgrade completes successfully, I have to go back and forth with PAI to correct issues. Then over the next couple of weeks, I continue discovering items that didn’t migrate correctly or aren’t functioning as expected.

It’s getting progressively more time-consuming with each version.

I keep all customizations in /USER, but even those don’t seem to be cleanly recognized after an upgrade. I’m trying to determine whether this is something I’m doing incorrectly or if there’s a more reliable upgrade strategy I should be following.

For those who have a smoother experience:

• What does your upgrade process look like end-to-end?
• Are you doing anything beyond the documented steps (diff checks, clean installs, config validation, etc.)?
• How are you validating that customizations in /USER are being preserved correctly?
• Do you treat upgrades as rebuilds rather than in-place transitions?

Looking for a more disciplined, predictable approach because the current cycle isn’t sustainable.

I’ve had the same issue. The last upgrade to 3.0 didn’t go very smoothly.I reverted back to my old 2.4 version and then told PAI to just go cherry pick some things out of the new algorithm that I wanted. I then integrated those new Cherry picks into my current version. This worked well. This is my plan from here on out. It’s just too much work to wholesale install again and fix bugs.

[danielmiessler]

We just posted 4.0.0, which should solve a lot of these problems! Daniel

…

On Fri, Feb 27, 2026 at 3:33 PM, jarednwilson < ***@***.*** > wrote: > > > I’ve been using PAI since v2.0, and with every upgrade I end up spending a > significant amount of time troubleshooting after following the documented > upgrade path. Even when the upgrade completes successfully, I have to go > back and forth with PAI to correct issues. Then over the next couple of > weeks, I continue discovering items that didn’t migrate correctly or > aren’t functioning as expected. > > > > It’s getting progressively more time-consuming with each version. > > > > I keep all customizations in /USER , but even those don’t seem to be > cleanly recognized after an upgrade. I’m trying to determine whether this > is something I’m doing incorrectly or if there’s a more reliable upgrade > strategy I should be following. > > > > For those who have a smoother experience: > > > > * What does your upgrade process look like end-to-end? > * Are you doing anything beyond the documented steps (diff checks, clean > installs, config validation, etc.)? > * How are you validating that customizations in /USER are being preserved > correctly? > * Do you treat upgrades as rebuilds rather than in-place transitions? > > > > > Looking for a more disciplined, predictable approach because the current > cycle isn’t sustainable. > > I’ve had the same issue. The last upgrade to 3.0 I reverted back to my old 2.4 I think is what the prior one was and then told PAI to just go cherry pick some things out of the new algorithm that I wanted and integrated into my current version that is my plan from here on out. It’s just too much work to wholesale install again and fix bugs. — Reply to this email directly, view it on GitHub ( #754 (comment) ) , or unsubscribe ( https://github.com/notifications/unsubscribe-auth/AAAMLXREATG5TSHFMAVY2UL4ODH3RAVCNFSM6AAAAACV3QNHPCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKOJVGE4DQMQ ). You are receiving this because you were mentioned. Message ID: <danielmiessler/Personal_AI_Infrastructure/repo-discussions/754/comments/15951882 @ github. com>

[kaimagnus]

Thanks for the detailed feedback — this is exactly the kind of thing that helps us improve.

v4.0.1 addresses several of these issues:

• Upgrade path documentation — The README now has separate Fresh Install and Upgrading sections with explicit backup, merge, and post-upgrade checklist steps
• Configurable temperature units — New preferences.temperatureUnit field in settings.json (Fahrenheit or Celsius). The installer prompts for it, and the statusline honors it
• Hardcoded timezone removed — Statusline now reads principal.timezone from settings instead of hardcoded America/Los_Angeles (PR fix(statusline): read timezone from settings.json instead of hardcoding #762)
• Broken context fallback removed — The /clear stale percentage issue is fixed (PR fix(statusline): remove broken context percentage fallback after /clear #806)
• Startup estimate removed — The self-calibrating estimate that inflated fresh session context % is gone
• f-string syntax fix — Nested quoting issue in Python eval block resolved (PR fix(statusline): fix f-string syntax error silently breaking reset time display #780)
• FAQ fixes — Removed stale Python reference, improved recovery guidance

Grab the release: v4.0.1

Appreciate you taking the time to report this.