From d19edbebfb7cfebf8a785629a469c96966e1c3ba Mon Sep 17 00:00:00 2001
From: sck_0 <samujackson1337@gmail.com>
Date: Mon, 26 Jan 2026 08:46:15 +0100
Subject: [PATCH] docs: add critical CI drift fixation guide and update
 maintenance routine

---
 .github/MAINTENANCE.md | 18 +++++++++++++++++-
 docs/CI_DRIFT_FIX.md   | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 docs/CI_DRIFT_FIX.md

diff --git a/.github/MAINTENANCE.md b/.github/MAINTENANCE.md
index ca520ac9..6c5fbbaa 100644
--- a/.github/MAINTENANCE.md
+++ b/.github/MAINTENANCE.md
@@ -22,10 +22,26 @@ Before ANY commit that adds/modifies skills, run the chain:
     _Must return 0 errors for new skills._
 
 2.  **Regenerate Index**:
-    ```bash
     python3 scripts/generate_index.py
+
     ```
 
+    ```
+
+3.  **Update Readme**:
+
+    ```bash
+    python3 scripts/update_readme.py
+    ```
+
+4.  **COMMIT GENERATED FILES**:
+    ```bash
+    git add skills_index.json README.md
+    git commit -m "chore: sync generated files"
+    ```
+    > 🔴 **CRITICAL**: If you skip this, CI will fail with "Detected uncommitted changes".
+    > See [docs/CI_DRIFT_FIX.md](../docs/CI_DRIFT_FIX.md) for details.
+
 ### B. Post-Merge Routine (Must Do)
 
 After multiple PR merges or significant changes:
diff --git a/docs/CI_DRIFT_FIX.md b/docs/CI_DRIFT_FIX.md
new file mode 100644
index 00000000..41eeb941
--- /dev/null
+++ b/docs/CI_DRIFT_FIX.md
@@ -0,0 +1,38 @@
+# CI Drift Fix Guide
+
+**Problem**: The failing job is caused by uncommitted changes detected in `README.md` or `skills_index.json` after the update scripts run.
+
+**Error**:
+
+```
+❌ Detected uncommitted changes in README.md or skills_index.json. Please run scripts locally and commit.
+```
+
+**Cause**:
+Scripts like `scripts/generate_index.py` and `scripts/update_readme.py` modify `README.md` and `skills_index.json`, but the workflow expects these files to have no changes after the scripts are run. Any differences mean the committed repo is out-of-sync with what the generation scripts produce.
+
+**How to Fix (DO THIS EVERY TIME):**
+
+1. Run the scripts locally to regenerate README.md and skills_index.json:
+
+   ```bash
+   python3 scripts/generate_index.py
+   python3 scripts/update_readme.py
+   ```
+
+2. Check for changes:
+
+   ```bash
+   git status
+   git diff
+   ```
+
+3. Commit and push any updates:
+   ```bash
+   git add README.md skills_index.json
+   git commit -m "Update README and skills index to resolve CI drift"
+   git push
+   ```
+
+**Summary**:
+Always commit and push all changes produced by the registry or readme update scripts. This keeps the CI workflow passing by ensuring the repository and generated files are synced.