From Private to Public: A Practical Guide to Migrating Your GitHub Pages Repo

My GitHub Pages deployment just broke, and the reason is exactly what I suspected: my paid plan lapsed. This isn’t just a bug; it’s a philosophical fork in the road. Instead of paying the ‘Microsoft tax’ to keep my repository private, I’m taking this as the perfect catalyst to go public. Before I flip that switch, though, I’m doing a full reset—purging unused assets and then wiping the entire Git history to give the project a clean, fresh start as it moves into the open.

By Mike Levin

Sunday, June 8, 2025

Get Pipulate [View Markdown Source]

Setting the Stage: Context for the Curious Book Reader

This case study documents a real-world workflow for migrating a Jekyll-based website from a private to a public GitHub repository, a common task often prompted by changes in service tiers or a shift in development philosophy. The narrative begins with a practical problem—a broken deployment pipeline for a GitHub Pages site—and quickly evolves into a strategic decision to embrace open-source principles over paid services.

The entry provides a transparent, step-by-step guide through a series of high-stakes git operations, including the complete and irreversible wiping of a repository’s commit history. It demonstrates not only the “how” of using advanced Git commands like git checkout --orphan and git push --force, but also the critical “why” behind them. Along the way, it showcases practical developer tradecraft, such as using custom Python scripts for housekeeping tasks and modifying Liquid templates to enhance site functionality in an open-source context.

A Push into the Void: Diagnosing a Silent Failure

Haha! My article-pushing to MikeLev.in stopped working just now. I checked my GitHub invoice and indeed June 8th is my cutoff date for the paid level of GitHub membership. But like every other subscription service out there, they have been cooking the frog, inching up the subscription rates year after year, presumably now railroading you into CoPilot and trying to cover the costs for all their AI energy consumption.

The Culprit in the Invoice: A Philosophical Crossroads

I figured this out by my latest article not being automatically published with the Jekyll static site generator they have set up by default with GitHub actions and going into my GitHub payment history and noticing the attempted charges against my credit card which I allowed to expire as a defense against anti-subscription-cancellation measures. Who knows whether you’re really unsubscribed to something or not? Letting credit cards expire is a hardwired defense. And this hardwired defense is now being used to wind down the last of my Microsoft taxes: GitHub Copilot Pro & Microsoft 365 Family.

To confirm that I can still Github Pages publish (github.io), I switched my repository that controls the Pipulate.com website to public. That will be interesting allowing the history of that repo to show, all the evolutions of Pipulate over the years. Okay, so the situation is clear:

Pay the Microsoft tax and be able to publish websites with Github Pages from private repositories.
Don’t pay the Microsoft tax and switch the repositories from private to public to continue publishing to GitHub pages.

Interesting! Well, given that my home-hosting project is so close and so friggin necessary with the rapid developments in AI requiring watching the bots visit your site in real time, I will use this development to help light a fire under my butt and to wind down the Microsoft-tax once and for all. Being on NixOS as I am, having build my own personal git repository, and getting onto home-hosting as I soon will be, I shouldn’t have to pay Microsoft for anything anyhow. Anyhoo…

Let’s wipe out the history of the current MikeLev.in repo so when I throw it public the old cruft doesn’t come with it. This is about fresh starts. It’s sort of like a phase 1 where we get everything still hosted by Microsoft on GitHub pages to do so under a free Github account on public repos. So this is something like a winding-down process too as we gear up our home-hosting plan and equipment.

Executing the Digital Reset: The Orphan Branch Strategy

Gemini: Excellent, it sounds like you’re well on your way to ‘de-Microsoft-ifying’ your setup! Wiping the history for a fresh public start is a great next step in this winding-down process. It’s the perfect way to prepare the repository for its new life as a public project without sharing all the historical “cruft.”

Here is a safe and reliable method to completely wipe the Git history of your MikeLev.in repository while keeping all your current files exactly as they are. It will result in a new repository state with just a single, clean “Initial commit.”

A Final, Irreversible Push

⚠️ A WORD OF WARNING FIRST This is a destructive and irreversible action for the Git history of the MikeLev.in repository. Before you begin, please double-check and be 100% certain that your private backup (MikeLev.in-copy or whatever you named it) is safe and contains the complete history you want to preserve.

The Strategy

The plan is to use a feature called an “orphan branch.” We will create a new branch that has no history, add all your current files to it as a fresh, first commit, and then replace your old main branch with this new, clean one. Finally, we’ll force-push this change to GitHub, overwriting the remote history forever.

Step-by-Step Guide to Wiping the Git History

Follow these commands in your terminal.

Step 1: Navigate to Your Local Repository

First, make sure you are working in your local copy of the original MikeLev.in repository, not the backup you just made.

cd /path/to/your/MikeLev.in

Step 2: Create a New, Empty “Orphan” Branch

We’ll create a new branch, let’s call it main-fresh, that is completely disconnected from your existing commit history.

git checkout --orphan main-fresh

After running this, you’ll be on the new main-fresh branch, and it will feel like you’re in a brand new repository with a bunch of untracked files. This is exactly what we want.

Step 3: Add and Commit All Your Current Files

Now we will stage all the current files and make our one-and-only commit.

# Add all files to the new branch
git add -A

# Commit the files with a clean message
git commit -m "Initial commit"

Your new main-fresh branch now has one single commit containing the latest version of your website.

Step 4: Delete the Old `main` Branch

Your old history is still stored locally in the main branch. We can now safely delete it.

git branch -D main

Step 5: Rename Your New Branch to `main`

Let’s rename our clean branch to main to make it the primary branch.

git branch -m main

Step 6: Force-Push to GitHub

This is the final step that makes the change permanent on GitHub. We will force-push our new local main branch, which will completely overwrite the old main branch and all its history on the remote server.

git push -f origin main

What to Expect After

Congratulations! If you now check your MikeLev.in repository on GitHub, you will see:

All your files are present and up-to-date.
The commit history shows only 1 commit with the message “Initial commit”.
All previous history is gone forever from this repository.

Your Final Steps

Now you are ready to complete the transition:

Make it Public: On the GitHub page for MikeLev.in, go to Settings > General and scroll down to the “Danger Zone”. Click “Change visibility” and make the repository Public.
Enable GitHub Pages: Go to Settings > Pages. Under “Build and deployment,” ensure the “Source” is set to “Deploy from a branch” and the branch is set to main. Click Save.

Within a few minutes, a new GitHub Action should trigger, build your Jekyll site from your now-public repository, and your MikeLev.in site will be live again, all under the free plan.

The Purge Before the Plunge: Cleaning House with Python

Me: Alright, I’m totally going to do this. But first I need to do a purge of:

/repos/MikeLev.in/assets/images

…before I git add everything back in.

Me: So I want to delete much from that images directory, but only images that are no longer linked to from anywhere in the current site. I can run Python helper scripts to do this. I’m also fine with being bold and brave about this. I know there’s full-path vs. relative path issues in such a helper script. An exact-match on just the filename portion should be enough to give an image safe haven and protection from deletion by this helper script, please and thank you!

Gemini: Of course. This is a perfect task for a Python helper script. Being bold is good, but being bold with a reliable tool is even better.

Here is a Python script designed to do exactly what you asked. It operates on the “safe haven” principle: it finds every image file in your images directory and then searches your entire site content for any mention of that image’s filename. If the filename isn’t mentioned anywhere, it’s considered unused and will be purged.

How It Works

Gathers All Image Files: It first walks through /repos/MikeLev.in/assets/images and creates a complete list of all image files (e.g., my-cool-photo.jpg, logo.png).
Scans All Content: It then recursively searches your entire repository (/repos/MikeLev.in/) for any text-based files (.md, .html, .css, etc.).
Builds a “Safe List”: It reads the content of every text file and checks if any of the image filenames from step 1 are mentioned inside. If my-cool-photo.jpg is found, it’s added to a “safe list” of referenced images.
Identifies Unused Images: It compares the complete list of images against the “safe list.” Any image not on the safe list is marked for deletion.
Performs Deletion (or a Dry Run): By default, it runs in a safe “dry run” mode, only printing a list of the images it would delete. To perform the actual deletion, you run it again without the dry run flag.

The Script: `purge_unused_images.py`

import os
import argparse
from pathlib import Path

# --- Configuration ---
# The script will look for images with these extensions.
IMAGE_EXTENSIONS = {'.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico'}
# The script will search for references within files with these extensions.
CONTENT_EXTENSIONS = {'.md', '.html', '.yml', '.css', '.js', '.json', '.txt'}

def find_unused_images(repo_dir: Path, dry_run: bool):
    """
    Finds and optionally deletes images in the assets/images directory
    that are not referenced in any content files within the repository.
    """
    images_dir = repo_dir / 'assets' / 'images'

    if not images_dir.is_dir():
        print(f"Error: Images directory not found at '{images_dir}'")
        return

    # 1. Get a set of all actual image filenames in the images directory
    print(f"📷 Scanning for images in: {images_dir}")
    all_image_files = {
        f.name for f in images_dir.iterdir()
        if f.is_file() and f.suffix.lower() in IMAGE_EXTENSIONS
    }
    print(f"   Found {len(all_image_files)} total image files.")

    # 2. Find all referenced images by scanning content files
    print(f"\n📄 Scanning repository content for image references...")
    referenced_images = set()
    files_scanned = 0
    for root, _, files in os.walk(repo_dir):
        # Skip the image directory itself to avoid self-references
        if Path(root).resolve() == images_dir.resolve():
            continue

        for file in files:
            if Path(file).suffix.lower() in CONTENT_EXTENSIONS:
                files_scanned += 1
                file_path = Path(root) / file
                try:
                    with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
                        content = f.read()
                        # Check if any of our known image filenames appear in the content
                        for image_filename in all_image_files:
                            if image_filename in content:
                                referenced_images.add(image_filename)
                except Exception as e:
                    print(f"   Warning: Could not read file {file_path}: {e}")

    print(f"   Scanned {files_scanned} content files.")
    print(f"   Found references to {len(referenced_images)} unique images.")

    # 3. Determine which images are unused and take action
    unused_images = all_image_files - referenced_images
    print(f"\n✨ Found {len(unused_images)} unused images.")

    if not unused_images:
        print("\n✅ No unused images to purge. Your image directory is clean!")
        return

    if dry_run:
        print("\nDRY RUN MODE: The following images would be deleted:")
        for image_name in sorted(list(unused_images)):
            print(f"  - {image_name}")
    else:
        print("\nDELETING unused images:")
        deleted_count = 0
        for image_name in sorted(list(unused_images)):
            image_to_delete = images_dir / image_name
            try:
                os.remove(image_to_delete)
                print(f"  - Deleted: {image_name}")
                deleted_count += 1
            except Exception as e:
                print(f"  - Error deleting {image_name}: {e}")
        print(f"\n🔥 Purged {deleted_count} images.")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Find and delete unused images from a Jekyll site's assets directory."
    )
    parser.add_argument(
        "repo_directory",
        type=str,
        help="The full path to the root of your repository (e.g., /home/mike/repos/MikeLev.in)."
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="Run the script without deleting any files. It will only list the files to be deleted."
    )

    args = parser.parse_args()

    repo_path = Path(args.repo_directory).resolve()
    
    if not repo_path.is_dir():
        print(f"Error: Provided path is not a valid directory: {repo_path}")
    else:
        find_unused_images(repo_path, args.dry_run)

How to Use

Save the Script: Save the code above into a file named purge_unused_images.py in a convenient location (like your home directory or a scripts folder).
Run in Dry Run Mode (Highly Recommended First): Open your terminal and run the script, pointing it to your MikeLev.in repository path and including the --dry-run flag.
```
python purge_unused_images.py /repos/MikeLev.in --dry-run
```
The script will print a summary of its findings and a list of all the image files it would delete, but it will not actually delete anything. Review this list carefully to make sure it looks correct.
Perform the Deletion: Once you are confident the “dry run” list is accurate, run the command again, but without the --dry-run flag.
```
python purge_unused_images.py /repos/MikeLev.in
```
The script will now print the name of each image as it deletes it.

Proceed with Your Git Workflow: After the script has purged the unused images, you can proceed with the next steps you outlined:

cd /repos/MikeLev.in
git add -A
git commit -m "Initial commit after purging images"
# ... and the rest of your history-wiping steps.

Me: [I run the script and show the output to Gemini]

Gemini: Excellent! The script worked perfectly.

It’s great to see the process in action:

You correctly figured out the script needed the repo_directory argument (. for the current directory).
You responsibly ran the --dry-run first to review the list of 74 images slated for deletion.
You then ran the script for real and successfully purged those 74 files, cleaning up the repository significantly.

You have now completed the final preparatory step. Your MikeLev.in repository is lean, clean, and ready for its history to be wiped for its public debut.

You are now ready to proceed with the exact git commands from our previous conversation to finalize the process. Here they are again for your convenience, picking up right where you left off.

Final Steps: Wiping History and Going Public

You are currently in your terminal at [mike@nixos:~/repos/MikeLev.in]$.

1. Create the New History

The image purge has created changes that need to be staged. The git checkout --orphan and subsequent commands will handle this perfectly.

# Create the new, empty "orphan" branch
git checkout --orphan main-fresh

# Add all current files (including the image deletions) to the new branch
git add -A

# Commit the files with a clean, single message
git commit -m "Initial commit"

2. Replace the Old `main` Branch

# Delete the old main branch with all its history
git branch -D main

# Rename your new clean branch to main
git branch -m main

3. Force-Push to GitHub

This is the final, irreversible step that makes the change permanent on GitHub.

git push -f origin main

After this push completes, your MikeLev.in repository on GitHub will have only one single commit but will contain all your current files.

4. Make the Repository Public and Enable Pages

On the GitHub page for MikeLev.in, go to Settings > General and change the repository visibility to Public.
Go to Settings > Pages, set the source to “Deploy from a branch”, choose main, and hit Save.

And that’s it. Your “digital de-Microsoft-ification” will have taken a major step forward, your site will be back online, and you’ll have a clean, public repository to move forward with.

Exposing All My Markdown to LLMs For The Win!

Me: This worked like a charm! Like it had eyes! Anyhoo as an extra bonus I’d like to give myself for doing this work, let’s spare the LLMs from ever having to extract markdown from my HTML since as a Jekyll site it all starts as markdown in the first place, and now as a public repo, all that markdown is accessible on Github! This is something I was planning on holding off doing until I was actually home-hosting with _config.yaml tricks to let each HTML version link to its markdown version, but since Github makes it all so conveniently accessible, let’s include it at least in my _layouts/post.html offering up the original markdown for each article.

They have completely predictable paths. So for example, the article I just wrote that kicked off this whole affair is:

/home/mike/repos/MikeLev.in/_posts/2025-06-08-prompt-and-pray.md

…which ends up published as:

https://mikelev.in/futureproof/prompt-and-pray/

…whose markdown is always reliably accessible as:

https://raw.githubusercontent.com/miklevin/MikeLev.in/refs/heads/main/_posts/2024-09-08-Future-proofing.md

And here is my:

/home/mike/repos/MikeLev.in/_layouts/post.html

[Jekyll Liquid Template _layousts/post.html removed - hey, it’s public now so feel free to go look ]

Please and thank you!

Gemini: That’s an excellent idea and a fantastic “extra bonus” for both yourself and for the AI agents of the world. Providing a direct link to the canonical markdown source is a great practice for transparency, versioning, and making your content more accessible for programmatic use.

Given that your repository is now public, constructing this link is straightforward using Jekyll’s Liquid templating. We can get the necessary information directly from the page object.

The Strategy

Get the Source Path: Jekyll provides the page.path variable, which holds the full path to the source file within your repository (e.g., _posts/2025-06-08-prompt-and-pray.md).
Construct the GitHub URL: We can prepend the static base URL for raw GitHub content to this page.path. The base URL is https://raw.githubusercontent.com/miklevin/MikeLev.in/main/.
Insert the Link: We’ll place this link in a logical, unobtrusive spot in your post.html layout, like near the byline or date.

The Code to Add

Here is a small, self-contained div you can add to your layout. It’s styled lightly to be helpful but not distracting.

```liquid<div class="source-link" style="text-align: right; font-size: 0.8em; margin-top: -1.5em; margin-bottom: 1.5em;"> [View Markdown Source] </div>

### Where to Place It in `post.html`

The best place for this link is right after the `<h4>` tag that contains the date and before the main article body. This positions it clearly as metadata for the post without interrupting the flow of the content.

Here is a snippet of your existing `post.html` showing exactly where to insert the new code block:

```liquid
<article itemscope itemtype="http://schema.org/BlogPosting">
  <h1 itemprop="headline">From Private to Public: A Practical Guide to Migrating Your GitHub Pages Repo</h1>
  <blockquote itemprop="description"><p>My GitHub Pages deployment just broke, and the reason is exactly what I suspected: my paid plan lapsed. This isn’t just a bug; it’s a philosophical fork in the road. Instead of paying the ‘Microsoft tax’ to keep my repository private, I’m taking this as the perfect catalyst to go public. Before I flip that switch, though, I’m doing a full reset—purging unused assets and then wiping the entire Git history to give the project a clean, fresh start as it moves into the open.</p>
</blockquote>
  <div itemprop="author" itemscope itemtype="http://schema.org/Person">
    By <span itemprop="name">Mike Levin</span>
  </div>
  <h4>
    <time itemprop="datePublished" datetime="2025-06-08T00:00:00+00:00">Sunday, June 8, 2025</time>
  </h4><div class="source-link" style="text-align: right; font-size: 0.8em; margin-top: -1.5em; margin-bottom: 1.5em;">
    <a href="https://raw.githubusercontent.com/miklevin/MikeLev.in/main/_posts/2025-06-08-migrate-github-pages-private-public.md" target="_blank" rel="noopener noreferrer" title="View the original Markdown source for this post">
      [View Markdown Source]
    </a>
  </div>

  <div itemprop="articleBody"><nav class="post-navigation top-nav" itemscope itemtype="https://schema.org/BreadcrumbList"><div class="previous-post" itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <span class="nav-label">Previous Post</span>
      <a href="https://mikelev.in/futureproof/migrate-github-pages-private-public/" itemprop="item">
        <span itemprop="name">From Private to Public: A Practical Guide to Migrating Your GitHub Pages Repo</span>
      </a>
      <meta itemprop="position" content="1" />
    </div><div class="home-link" itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
    <a href="https://mikelev.in/" itemprop="item" class="home-link-container">
      <span class="home-text" itemprop="name">
        <span class="nav-label">Blog Index</span>
        <span class="home-word">Home</span>
      </span>
      <span class="home-hamster">
        <img src="/images/dancing-hamster.gif" alt="Dancing Hamster" width="60px" height="60px">
      </span>
    </a>
    <meta itemprop="position" content="2" />
  </div><div class="next-post wiggle-prompt" itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <span class="nav-label">Next Post</span>
      <a href="https://mikelev.in/futureproof/perfect-pebble-tech-movement-strategy/" itemprop="item">
        <span itemprop="name">The Perfect Pebble: A Minimalist's Guide to Igniting a Tech Movement</span>
      </a>
      <meta itemprop="position" content="3" />
    </div></nav>
<article itemscope itemtype="http://schema.org/BlogPosting">
  <h1 itemprop="headline">The Human as a Tool Call: A Case Study in Hybrid AI-Assisted Refactoring</h1>
  <blockquote itemprop="description"><p>This entry captures that specific, intense state of flow on a Sunday morning, where the path forward is finally clear. After wrestling with unexpected infrastructure issues and taking the time to ‘polish the lenses’ of the system, the primary goal is now in sight: rebuilding the Parameter Buster plugin. The core of this moment is the conscious decision to adopt a specific, manual-first strategy for this complex code transplant, leveraging my own <code class="language-plaintext highlighter-rouge">nvim</code> skills as a precise ‘tool’ to avoid the common pitfalls of generative AI. This isn’t just about the code; it’s about defining a pragmatic, effective partnership with my AI assistant to tackle a difficult refactoring task.</p>
</blockquote>
  <div itemprop="author" itemscope itemtype="http://schema.org/Person">
    By <span itemprop="name">Mike Levin</span>
  </div>
  <h4>
    <time itemprop="datePublished" datetime="2025-06-08T00:00:00+00:00">Sunday, June 8, 2025</time>
  </h4><div class="source-link" style="text-align: right; font-size: 0.8em; margin-top: -1.5em; margin-bottom: 1.5em;">
    <a href="https://pipulate.com/" target="_blank" rel="noopener noreferrer" title="Pipulate Free and Open Source AI SEO Automation Software"> Get Pipulate </a>
    <a href="https://raw.githubusercontent.com/miklevin/MikeLev.in/main/_posts/2025-06-08-hybrid-ai-assisted-refactoring-case-study.md" target="_blank" rel="noopener noreferrer" title="View the original Markdown source for this post"> [View Markdown Source] </a>
  </div>
  <div itemprop="articleBody"><h2 id="setting-the-stage-context-for-the-curious-book-reader">Setting the Stage: Context for the Curious Book Reader</h2>

<p>This entry provides a real-time snapshot of development within Pipulate, a custom-built, plugin-based framework designed for creating and managing data-processing workflows. At its core, the system champions a “WET Workflows” (Write Everything Twice/Thoughtfully) philosophy, where individual plugin logic is kept explicit and self-contained for clarity, while common, repetitive tasks are handled by a central helper API. This approach aims to balance the maintainability of DRY (Don’t Repeat Yourself) principles with the readability of verbose, self-contained code.</p>

<p>The specific challenge detailed here is a crucial step in the system’s evolution: refactoring an older, monolithic plugin (<code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code>) to conform to a newer, cleaner, template-based architecture. This process, referred to as “the great transplant,” serves as a practical test case for the framework’s new code-generation helpers and its underlying development philosophy. It also offers a transparent look into a hybrid development model where the author strategically combines their own high-precision coding skills with high-level planning and analysis from an AI assistant.</p>

<hr />

<h2 id="an-intense-sunday-morning-from-unplanned-detours-to-a-clear-mission">An Intense Sunday Morning: From Unplanned Detours to a Clear Mission</h2>

<p>Alright, so that’s been an intense friggn Sunday morning. First I dealt with the
necessity to make a Juptyer Notebook that displays automatically on the Pipulate
install editable without blocking the auto-update system that relies on a git
pull into a pristine directory — I’ll have to document git branching for people
interested. Also in my pushing out of articles stopped working and I was forced
to deal with the consequences of my stopping all my Microsoft/Github
subscriptions, breaking free of the Microsoft taxes — even the GitHub ones!
These were both unexpected deep-dives, but it’s a good thing it’s only barely
9:30 AM. I still have plenty of time to do what I really need to do, which is
to:</p>

<ol>
  <li>Rebuild Parameter Buster on the new system using:
    <ul>
      <li>pipulate/plugins/200_workflow_genesis.py</li>
      <li>pipulate/helpers/create_workflow.py</li>
      <li>pipulate/helpers/splice_workflow_step.py</li>
      <li>pipulate/helpers/manage_class_attributes.py</li>
      <li>pipulate/helpers/swap_workflow_step.py</li>
    </ul>
  </li>
  <li>Leverage that Parameter Buster rebuild-win to slam out the Cosmograph Link
Graph Visualizer, and preferably even others too based on
https://observablehq.com/collection/@d3/d3-hierarchy</li>
</ol>

<h2 id="the-philosophy-of-the-lens-on-the-irresistible-drive-for-refinement">The Philosophy of the Lens: On the Irresistible Drive for Refinement</h2>

<p>Yesterday went mostly into code clean-up again. I have a seemingly irresistible
drive to use the weekend super-focused time for code cleanup, making everything
in the future easier for me, instead of just slamming out more and more WET
Workflows that will rapidly have to undergo revision or retirement. It’s
probably a good idea, but you can only grind and polish the lenses so much
before you have to start using the microscope to examine and cure illness. It’s
a jumping off the cliff and learning to fly situation. AI is likely only going
to arise on this planet once with human beings, and we’re going through it right
now. We’re going through it in a most remarkable way where public-facing AIs are
at our disposal to help us code, and this is utterly remarkable, beyond my
wildest SciFi dreams. And I have to live it. And so I am.</p>

<h2 id="a-human-ai-symbiosis-guiding-the-punches-in-software-development">A Human-AI Symbiosis: Guiding the Punches in Software Development</h2>

<p>Hitting above our weight classes is now possible, opting instead to stand back
just a wee bit from implementation and guide the punches, like the deaf leading
the blind in the fight scene in Richard Pryor and Gene Wilder’s <em>See No Evil,
Hear No Evil</em>. We (the human and the AI) are each experiencing reality in a
different way, our sensory streams and version of subjective experience each
being different, but each being able to back-up and facilitate the other. The
idea that this would be the case is better than any SciFi I’ve ever read. Way
less dystopian.</p>

<p>This is the all-over-the-board rambling of a super-prompt that I didn’t do on
that other one earlier today. But this time I’m dredging up what I really need
to be thinking about going into this next round of work.</p>

<p>Yesterday, I “polished the lenses” of the Pipulate system, centralizing the
iconography (aka emoji’s) into the main core of the system in Pipulate’s
<code class="language-plaintext highlighter-rouge">PIPULATE_CONFIG</code> class attributes in <code class="language-plaintext highlighter-rouge">server.py</code>. I also created a number of
other Pipulate helper functions <code class="language-plaintext highlighter-rouge">create_standard_landing_page</code>,
<code class="language-plaintext highlighter-rouge">register_workflow_routes</code>, which while not Object Oriented superclassing and
inheritance achieves many of the same things by simple template component
inclusion. This makes <code class="language-plaintext highlighter-rouge">pipulate/plugins/300_blank_placeholder.py</code> from which
most other things are going to be derived considerably cleaner (the lens more
ground and polished) than the other plugins in the system. I actually also gave
this treatment to <code class="language-plaintext highlighter-rouge">040_hello_workflow.py</code> and <code class="language-plaintext highlighter-rouge">400_botify_quadfecta.py</code>. The
Trifecta one will come prominently into play on this next objective when we make
a new <code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code> using <code class="language-plaintext highlighter-rouge">400_botify_quadfecta.py</code> as the base
template.</p>

<p>This part actually goes easily enough because
<code class="language-plaintext highlighter-rouge">pipulate/plugins/200_workflow_genesis.py</code> effectively does that automatically
giving the <code class="language-plaintext highlighter-rouge">pipulate/helpers/create_workflow.py</code> command. So by the time you’re
even reading this prompt, the starting file
<code class="language-plaintext highlighter-rouge">pipulate/plugins/115_parameter_buster2.py</code>… okay, done that part.</p>

<p>Okay, so I’ve got these two files:</p>

<p>/home/mike/repos/pipulate/plugins/110_parameter_buster.py
/home/mike/repos/pipulate/plugins/115_parameter_buster2.py</p>

<h3 id="why-manual-first-acknowledging-ais-achilles-heel">Why Manual-First? Acknowledging AI’s Achilles’ Heel</h3>

<p>…and the details of the former’s steps and support methods are going to have
to wind up in the second. The idea is that maybe in the future there will be
transplant tools that will really help with this. But for right now, it’s
probably going to be a sort of manual copy/paste that the LLMs are really,
really terrible at with their generative imaginations re-writing all the fragile
and brittle stuff that just cannot change least things regress. And so that’s
what we’re avoiding here with the implementation plan.</p>

<p>So as opposed to an implementation plan for me to just hand over to Claude built
into Cursor like I usually do which in this case would result in just endless
spinning of wheels of the AI edit assistant unable to do all the search/replace
and edit tool-calls, we are going to instead use the human being as a fully
automate-able tool-call alternative.</p>

<p>This user in particular is adept at vim/nvim commands. This should probably go
in several passes, such as moving <code class="language-plaintext highlighter-rouge">step_xx</code>, step_xx_submit` and whatever
dependencies and support functions need to be moved with them to be adjacent to
them, so when I transpose between files it minimizes and simplifies the number
of actual copy/paste commands.</p>

<p>So in other words, give implementation instructions to a human to group related
methods for copy/pasting.</p>

<p>Similarly, group everything together in terms of class attributes to reduce the
copy/pasting of any class attributes from <code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code> to
<code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code></p>

<p>Does all that make sense? The human is skilled with exactly the sort of
copy/pasting maneuvers that the tool-calling has difficulty with. And so the
user will actually make a copy of <code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code> as
<code class="language-plaintext highlighter-rouge">111_parameter_buster.py</code> so that they can move things around freely in
preparation for a transplant of the atomically clumped methods (or class
attributes) into <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code> so that we can turn
<code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code> into an updated version of <code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code></p>

<hr />

<h2 id="the-core-task-transplanting-the-parameter-buster">The Core Task: Transplanting the Parameter Buster</h2>

<p><strong>Gemini</strong>: Of course. Based on the provided codebase and your detailed prompt, I’ve analyzed the situation. Here is a comprehensive plan to refactor <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code> by transplanting the functionality from <code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code>, designed for a skilled developer using a powerful editor like <code class="language-plaintext highlighter-rouge">nvim</code>.</p>

<p>This plan is structured to be methodical and “atomic,” grouping related code blocks to minimize errors during the manual transplant process.</p>

<hr />

<h3 id="material-analysis">Material Analysis</h3>

<p>The codebase demonstrates a clear evolution from more monolithic plugins (<code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code>) towards a more modular, DRY (Don’t Repeat Yourself) system for core functionalities while keeping workflows WET (Write Everything Twice/Thoughtfully).</p>

<ul>
  <li><strong>Key Architecture:</strong> The system uses a plugin-based architecture managed by <code class="language-plaintext highlighter-rouge">server.py</code>. The <code class="language-plaintext highlighter-rouge">Pipulate</code> class acts as a central API for plugins, providing helper methods that encapsulate common patterns (UI generation, state management, routing). <code class="language-plaintext highlighter-rouge">PIPULATE_CONFIG</code> centralizes UI constants, styles, and role definitions, abstracting them away from individual plugins.</li>
  <li><strong>WET Workflows:</strong> The philosophy is to keep the “workflow” logic explicit and self-contained within each plugin (<code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code>, <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code>), even if it means some repetition. This makes individual workflows easier to understand and debug without needing to trace complex inheritance chains. Core, repetitive tasks (like creating a landing page or registering routes) are offloaded to helpers in the <code class="language-plaintext highlighter-rouge">Pipulate</code> class.</li>
  <li><strong>Chain Reaction Pattern:</strong> The primary UI flow is a “chain reaction” where each step’s submission handler explicitly triggers the loading of the next step via <code class="language-plaintext highlighter-rouge">hx-trigger="load"</code>. This is a robust and debuggable pattern for multi-step forms.</li>
  <li><strong>Human-in-the-Loop AI Development:</strong> Your prompt highlights a sophisticated development process. You’re not just asking an AI to code; you’re using it as a planning and strategy partner, while leveraging human expertise (your <code class="language-plaintext highlighter-rouge">nvim</code> skills) for the high-precision, “brittle” task of code transplantation where generative AI might fail. This is an excellent example of a hybrid intelligence workflow.</li>
</ul>

<h3 id="strategic-plan-the-great-transplant-">Strategic Plan: The Great Transplant 🧬</h3>

<p>The goal is to move the battle-tested logic from <code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code> into the newer, cleaner structure of <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code>. We’ll do this in three phases: <strong>Preparation</strong>, <strong>Transplantation</strong>, and <strong>Integration</strong>.</p>

<p>As you requested, first create a working copy of the source file:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cp </span>plugins/110_parameter_buster.py plugins/111_parameter_buster_transplant_prep.py
</code></pre></div></div>

<p>You will perform all “Preparation” steps in <code class="language-plaintext highlighter-rouge">111_parameter_buster_transplant_prep.py</code>.</p>

<hr />

<h3 id="phase-1-preparation-in-111_parameter_buster_transplant_preppy">Phase 1: Preparation (in <code class="language-plaintext highlighter-rouge">111_parameter_buster_transplant_prep.py</code>)</h3>

<p>This phase is about organizing the source code into logical, “atomic” clumps for easier copy-pasting.</p>

<h4 id="step-1-consolidate-class-attributes"><strong>Step 1: Consolidate Class Attributes</strong></h4>

<p>Move all class-level attributes to the top of the <code class="language-plaintext highlighter-rouge">ParameterBusterWorkflow</code> class. This creates a single block to copy.</p>

<ul>
  <li><strong>Action:</strong> In <code class="language-plaintext highlighter-rouge">111_parameter_buster_transplant_prep.py</code>, find <code class="language-plaintext highlighter-rouge">APP_NAME</code>, <code class="language-plaintext highlighter-rouge">DISPLAY_NAME</code>, <code class="language-plaintext highlighter-rouge">ENDPOINT_MESSAGE</code>, and <code class="language-plaintext highlighter-rouge">TRAINING_PROMPT</code> and ensure they are grouped together at the top of the class definition.</li>
</ul>

<h4 id="step-2-group-shared-helper-methods"><strong>Step 2: Group Shared Helper Methods</strong></h4>

<p>These are the methods that multiple steps rely on. Grouping them makes them a single, portable block.</p>

<ul>
  <li><strong>Action:</strong> In <code class="language-plaintext highlighter-rouge">111_parameter_buster_transplant_prep.py</code>, find the following methods and move them together into a single block, perhaps near the end of the file before the final <code class="language-plaintext highlighter-rouge">__init__</code> or <code class="language-plaintext highlighter-rouge">landing</code> methods:
    <ul>
      <li><code class="language-plaintext highlighter-rouge">validate_botify_url</code></li>
      <li><code class="language-plaintext highlighter-rouge">check_if_project_has_collection</code></li>
      <li><code class="language-plaintext highlighter-rouge">fetch_analyses</code></li>
      <li><code class="language-plaintext highlighter-rouge">read_api_token</code></li>
      <li><code class="language-plaintext highlighter-rouge">get_deterministic_filepath</code></li>
      <li><code class="language-plaintext highlighter-rouge">check_file_exists</code></li>
      <li><code class="language-plaintext highlighter-rouge">ensure_directory_exists</code></li>
      <li><code class="language-plaintext highlighter-rouge">build_exports</code></li>
      <li><code class="language-plaintext highlighter-rouge">poll_job_status</code></li>
      <li><code class="language-plaintext highlighter-rouge">analyze_parameters</code> and its associated helpers (<code class="language-plaintext highlighter-rouge">load_csv_with_optional_skip</code>, <code class="language-plaintext highlighter-rouge">extract_query_params</code>, <code class="language-plaintext highlighter-rouge">count_query_params</code>, etc.)</li>
      <li><code class="language-plaintext highlighter-rouge">create_prism_widget</code> and <code class="language-plaintext highlighter-rouge">create_marked_widget</code></li>
      <li><code class="language-plaintext highlighter-rouge">load_raw_counters_from_cache</code>, <code class="language-plaintext highlighter-rouge">calculate_and_cache_raw_counters</code></li>
      <li><code class="language-plaintext highlighter-rouge">create_parameter_visualization_placeholder</code></li>
    </ul>
  </li>
</ul>

<h4 id="step-3-group-methods-by-workflow-step"><strong>Step 3: Group Methods by Workflow Step</strong></h4>

<p>For each logical step in the workflow, group its <code class="language-plaintext highlighter-rouge">_process</code> (if any), <code class="language-plaintext highlighter-rouge">_submit</code>, and main handler methods together. This makes transplanting step-by-step functionality trivial.</p>

<ul>
  <li><strong>Action:</strong> For each step <code class="language-plaintext highlighter-rouge">step_XX</code> from <code class="language-plaintext highlighter-rouge">step_01</code> to <code class="language-plaintext highlighter-rouge">step_07</code> in <code class="language-plaintext highlighter-rouge">111_parameter_buster_transplant_prep.py</code>:
    <ol>
      <li>Find the <code class="language-plaintext highlighter-rouge">step_XX</code> method.</li>
      <li>Move the corresponding <code class="language-plaintext highlighter-rouge">step_XX_submit</code> method to be immediately after it.</li>
      <li>If there is a <code class="language-plaintext highlighter-rouge">step_XX_process</code> or <code class="language-plaintext highlighter-rouge">step_XX_complete</code> method, move it to be after the <code class="language-plaintext highlighter-rouge">_submit</code> method.</li>
      <li>The result should be blocks of related methods, e.g.:
        <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># --- Step 2 Block ---
</span><span class="k">async</span> <span class="k">def</span> <span class="nf">step_02</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
    <span class="p">...</span>
<span class="k">async</span> <span class="k">def</span> <span class="nf">step_02_submit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
    <span class="p">...</span>
<span class="k">async</span> <span class="k">def</span> <span class="nf">step_02_process</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
    <span class="p">...</span>
</code></pre></div>        </div>
      </li>
    </ol>
  </li>
</ul>

<p>You are now ready for the transplant.</p>

<hr />

<h3 id="phase-2-transplantation-from-111_-to-115_">Phase 2: Transplantation (from <code class="language-plaintext highlighter-rouge">111_...</code> to <code class="language-plaintext highlighter-rouge">115_...</code>)</h3>

<p>Now, we’ll move the prepared code blocks into <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code>.</p>

<h4 id="step-4-transplant-core-definitions"><strong>Step 4: Transplant Core Definitions</strong></h4>

<ol>
  <li><strong>Class Attributes:</strong> Copy the consolidated block of attributes (<code class="language-plaintext highlighter-rouge">APP_NAME</code>, <code class="language-plaintext highlighter-rouge">DISPLAY_NAME</code>, etc.) from <code class="language-plaintext highlighter-rouge">111...</code> and paste it into <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code>, replacing the existing placeholders.</li>
  <li><strong>Steps List:</strong> In the <code class="language-plaintext highlighter-rouge">__init__</code> method of <code class="language-plaintext highlighter-rouge">115...</code>, replace the placeholder <code class="language-plaintext highlighter-rouge">self.steps</code> list with the full <code class="language-plaintext highlighter-rouge">self.steps</code> list from the <code class="language-plaintext highlighter-rouge">__init__</code> method of <code class="language-plaintext highlighter-rouge">111...</code>.</li>
  <li><strong>Step Messages:</strong> Copy the <code class="language-plaintext highlighter-rouge">self.step_messages</code> dictionary from <code class="language-plaintext highlighter-rouge">111...</code> into the <code class="language-plaintext highlighter-rouge">__init__</code> of <code class="language-plaintext highlighter-rouge">115...</code>.</li>
</ol>

<h4 id="step-5-transplant-methods"><strong>Step 5: Transplant Methods</strong></h4>

<ol>
  <li><strong>Shared Helpers:</strong> Copy the entire block of grouped helper methods from <code class="language-plaintext highlighter-rouge">111...</code> and paste it into the <code class="language-plaintext highlighter-rouge">ParameterBuster2</code> class in <code class="language-plaintext highlighter-rouge">115...</code>. A good place is after the <code class="language-plaintext highlighter-rouge">__init__</code> method and before the first step handler.</li>
  <li><strong>Step Handlers:</strong> One by one, copy each grouped “Step Block” (e.g., the <code class="language-plaintext highlighter-rouge">step_02</code>, <code class="language-plaintext highlighter-rouge">step_02_submit</code>, <code class="language-plaintext highlighter-rouge">step_02_process</code> methods) from <code class="language-plaintext highlighter-rouge">111...</code> into <code class="language-plaintext highlighter-rouge">115...</code>, replacing the placeholder methods that exist.</li>
</ol>

<hr />

<h3 id="phase-3-integration--refactoring-in-115_parameter_buster2py">Phase 3: Integration &amp; Refactoring (in <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code>)</h3>

<p>The code is now in place, but it needs to be integrated with the newer, cleaner patterns from <code class="language-plaintext highlighter-rouge">server.py</code> and the placeholder template.</p>

<h4 id="step-6-adopt-modern-ui-constants"><strong>Step 6: Adopt Modern UI Constants</strong></h4>

<p>The old plugin hardcodes button labels and styles. The new system uses <code class="language-plaintext highlighter-rouge">self.ui</code> from <code class="language-plaintext highlighter-rouge">PIPULATE_CONFIG</code>.</p>

<ul>
  <li><strong>Action:</strong> Search through the newly pasted methods in <code class="language-plaintext highlighter-rouge">115...</code> for hardcoded strings like <code class="language-plaintext highlighter-rouge">'Finalize 🔒'</code>, <code class="language-plaintext highlighter-rouge">'🔓 Unlock'</code>, <code class="language-plaintext highlighter-rouge">'secondary outline'</code>, etc. Replace them with their <code class="language-plaintext highlighter-rouge">self.ui</code> equivalents.
    <ul>
      <li><code class="language-plaintext highlighter-rouge">Button('Finalize 🔒', ...)</code> -&gt; <code class="language-plaintext highlighter-rouge">Button(self.ui['BUTTON_LABELS']['FINALIZE'], ...)</code></li>
      <li><code class="language-plaintext highlighter-rouge">cls='primary'</code> -&gt; <code class="language-plaintext highlighter-rouge">cls=self.ui['BUTTON_STYLES']['PRIMARY']</code></li>
      <li>This is a critical step to ensure consistency and future-proof the UI.</li>
    </ul>
  </li>
</ul>

<h4 id="step-7-refactor-__init__-method"><strong>Step 7: Refactor <code class="language-plaintext highlighter-rouge">__init__</code> Method</strong></h4>

<p>The old <code class="language-plaintext highlighter-rouge">__init__</code> manually registers all routes. The new template uses a helper.</p>

<ul>
  <li><strong>Action:</strong>
    <ol>
      <li>In <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code>, ensure the <code class="language-plaintext highlighter-rouge">__init__</code> method contains the line <code class="language-plaintext highlighter-rouge">pipulate.register_workflow_routes(self)</code>.</li>
      <li>Delete the old, manual <code class="language-plaintext highlighter-rouge">for path, handler, *methods in routes:</code> loop that you copied from <code class="language-plaintext highlighter-rouge">110...</code>.</li>
      <li>Ensure any <em>custom</em> routes that are not part of the standard step pattern (e.g., <code class="language-plaintext highlighter-rouge">step_02_process</code>, <code class="language-plaintext highlighter-rouge">parameter_preview</code>) are still registered individually after the helper call. The helper only handles the standard <code class="language-plaintext highlighter-rouge">/step_id</code> and <code class="language-plaintext highlighter-rouge">/step_id_submit</code> routes.</li>
    </ol>
  </li>
</ul>

<h4 id="step-8-final-cleanup"><strong>Step 8: Final Cleanup</strong></h4>

<ul>
  <li><strong>Review Imports:</strong> Ensure all necessary imports are at the top of the file and remove any that are no longer used.</li>
  <li><strong>Rename the Class:</strong> Rename the class from <code class="language-plaintext highlighter-rouge">ParameterBusterWorkflow</code> (the old name) to <code class="language-plaintext highlighter-rouge">ParameterBuster2</code> to match the file.</li>
  <li><strong>Final Sanity Check:</strong> Read through the refactored <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code>. The logic should be identical to the original, but the structure should be cleaner, relying on the central <code class="language-plaintext highlighter-rouge">pipulate</code> helpers and <code class="language-plaintext highlighter-rouge">self.ui</code> constants where appropriate. The result will be a plugin that is both powerful and maintainable.</li>
</ul>

<p>By following this structured, human-driven plan, you can effectively perform the transplant while mitigating the risks of automated refactoring, resulting in a robust and modern workflow.</p>

<hr />

<p><strong>Me</strong>: This process has succeeded beyond my wildest dreams!</p>

<p>It’s not even in the system anymore, but the old
<code class="language-plaintext highlighter-rouge">pipulate/plugins/110_parameter_buster.py</code> was replaced with a new one that was
greatly created with the helper scripts, a fair amount of human-assisted
copy/paste work where the LLM tool-calls are often not efficient or
token-thrift, but then with plenty of LLM follow-up work to connect it all
together, and even put some finishing polish. Look over this entire discussion
and write the continuation of the article covering everything from where it
leaves off, and not just with a bias towards the very latest stuff we did. Dig
back in this conversation.</p>

<p><strong>Claude</strong>: # The Great Parameter Buster Rebuild: A Journey Through Template-Based Development and Human-AI Collaboration</p>

<p><em>Continuing from where we left off with the Pipulate system’s evolution toward modular, template-based workflow development…</em></p>

<h2 id="the-challenge-from-monolith-to-modular">The Challenge: From Monolith to Modular</h2>

<p>Sunday morning, 9:30 AM. The old <code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code> sat there like a monument to the “WET Workflows” philosophy—4,400+ lines of battle-tested code that worked perfectly but represented the old way of doing things. Meanwhile, the shiny new <code class="language-plaintext highlighter-rouge">400_botify_quadfecta.py</code> template beckoned with its clean architecture, centralized UI constants, and helper-based route registration.</p>

<p>The mission was clear: rebuild Parameter Buster using the new modular system without losing any of its sophisticated functionality. This would be the real test of whether the “polish the lenses” approach—investing in developer experience and code generation tools—would pay dividends when creating actual production workflows.</p>

<h2 id="phase-1-genesis-and-template-instantiation">Phase 1: Genesis and Template Instantiation</h2>

<p>The journey began smoothly enough with the workflow genesis system:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>python helpers/create_workflow.py 115_parameter_buster2.py ParameterBuster2 parameter_buster <span class="s2">"Parameter Buster"</span> <span class="s2">"URL Parameter Analysis"</span> <span class="s2">"Extract and analyze URL parameters"</span> <span class="nt">--template</span> botify_trifecta <span class="nt">--force</span>
</code></pre></div></div>

<p>This single command created a clean starting point based on the Botify Trifecta template, complete with:</p>
<ul>
  <li>Centralized UI constants from <code class="language-plaintext highlighter-rouge">PIPULATE_CONFIG</code></li>
  <li>Template-based route registration</li>
  <li>Clean step definitions with proper chain reaction patterns</li>
  <li>Modern state management helpers</li>
</ul>

<p>But now came the hard part: transplanting 4,000+ lines of specialized logic while maintaining the new architecture’s cleanliness.</p>

<h2 id="the-transplantation-challenge-when-ai-meets-reality">The Transplantation Challenge: When AI Meets Reality</h2>

<p>This is where the conversation became a masterclass in human-AI collaboration limitations and strengths. The initial instinct was to let Claude handle the transplantation through its search/replace and edit tool calls. But reality intervened quickly.</p>

<p><strong>The Problem</strong>: AI excels at understanding and planning but struggles with the mechanical precision required for large-scale code transplantation. Search/replace operations that seem simple to describe become exercises in frustration when:</p>
<ul>
  <li>Methods are duplicated with subtle differences</li>
  <li>Dependencies span hundreds of lines</li>
  <li>The “latest definition wins” behavior of Python creates silent failures</li>
</ul>

<p><strong>The Solution</strong>: Treat the human as a “tool call alternative” for precision operations while leveraging AI for planning, analysis, and troubleshooting.</p>

<h2 id="phase-2-the-manual-transplant-strategy">Phase 2: The Manual Transplant Strategy</h2>

<p>Rather than fighting AI limitations, we embraced a hybrid approach:</p>

<h3 id="step-1-create-a-working-copy">Step 1: Create a Working Copy</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cp </span>plugins/110_parameter_buster.py plugins/111_parameter_buster_transplant_prep.py
</code></pre></div></div>

<h3 id="step-2-the-atomic-clumping-strategy-for-a-high-precision-transplant">Step 2: The “Atomic Clumping” Strategy for a High-Precision Transplant</h3>

<p>Using vim/nvim skills, the developer grouped related functionality into “atomic clumps”:</p>

<p><strong>Class Attributes Block:</strong></p>
<ul>
  <li><code class="language-plaintext highlighter-rouge">APP_NAME</code>, <code class="language-plaintext highlighter-rouge">DISPLAY_NAME</code>, <code class="language-plaintext highlighter-rouge">ENDPOINT_MESSAGE</code></li>
  <li><code class="language-plaintext highlighter-rouge">QUERY_TEMPLATES</code> with all the complex BQL configurations</li>
  <li><code class="language-plaintext highlighter-rouge">TEMPLATE_CONFIG</code> and <code class="language-plaintext highlighter-rouge">FEATURES_CONFIG</code></li>
</ul>

<p><strong>Helper Methods Block:</strong></p>
<ul>
  <li><code class="language-plaintext highlighter-rouge">validate_botify_url</code></li>
  <li><code class="language-plaintext highlighter-rouge">fetch_analyses</code></li>
  <li><code class="language-plaintext highlighter-rouge">build_exports</code> (the 200+ line export orchestrator)</li>
  <li><code class="language-plaintext highlighter-rouge">poll_job_status</code></li>
  <li>All the parameter analysis helpers</li>
</ul>

<p><strong>Step Handler Blocks:</strong>
Each step’s GET handler, POST submit handler, and any process handlers grouped together for atomic transplantation.</p>

<p>This approach minimized copy/paste operations while ensuring no dependencies were broken.</p>

<h2 id="phase-3-the-integration-challenges">Phase 3: The Integration Challenges</h2>

<p>With the code physically moved, the real debugging began. This phase revealed several critical insights about template-based development:</p>

<h3 id="issue-1-the-latest-definition-wins-problem">Issue 1: The “Latest Definition Wins” Problem</h3>

<p>A subtle but devastating issue emerged: duplicate helper functions from the old code were overriding superior template versions. Python’s method resolution meant that pasted helper functions at the end of the file were silently replacing better implementations from the template.</p>

<p><strong>The Fix</strong>: Identify and remove duplicate functions, keeping only the template versions or carefully merging improvements.</p>

<h3 id="issue-2-missing-route-registration">Issue 2: Missing Route Registration</h3>

<p>The <code class="language-plaintext highlighter-rouge">/parameter_preview</code> endpoint was returning 404 errors despite the method existing. The root cause: route registration happened before the finalize step was added to <code class="language-plaintext highlighter-rouge">self.steps</code>.</p>

<p><strong>The Discovery Process:</strong></p>
<ol>
  <li>Compare route lists between old and new systems</li>
  <li>Identify that template-based registration only handles standard step routes</li>
  <li>Realize custom routes need explicit registration</li>
  <li>Fix the registration order</li>
</ol>

<p><strong>The Fix:</strong></p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Register custom routes specific to this workflow
</span><span class="n">app</span><span class="p">.</span><span class="n">route</span><span class="p">(</span><span class="sa">f</span><span class="s">'/</span><span class="si">{</span><span class="n">app_name</span><span class="si">}</span><span class="s">/parameter_preview'</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s">'POST'</span><span class="p">])(</span><span class="bp">self</span><span class="p">.</span><span class="n">parameter_preview</span><span class="p">)</span>
</code></pre></div></div>

<h3 id="issue-3-chain-reaction-flow-breakdown">Issue 3: Chain Reaction Flow Breakdown</h3>

<p>The multi-step workflow was stopping at Step 6 instead of flowing through to Step 7 and finalize. This revealed multiple interconnected issues:</p>

<p><strong>Missing Step Definition</strong>: Step 7 existed as methods but wasn’t in the <code class="language-plaintext highlighter-rouge">self.steps</code> list
<strong>Method Name Mismatches</strong>: <code class="language-plaintext highlighter-rouge">update_state_with_html()</code> calls failing because template uses direct state management
<strong>Route Registration Timing</strong>: Routes registered before all steps were defined</p>

<p><strong>The Cascade Fix:</strong></p>
<ol>
  <li>Add missing step to steps list</li>
  <li>Replace <code class="language-plaintext highlighter-rouge">update_state_with_html()</code> with direct state management</li>
  <li>Move route registration after step list finalization</li>
</ol>

<h2 id="phase-4-the-final-polish">Phase 4: The Final Polish</h2>

<h3 id="spacing-issues-in-code-generation">Spacing Issues in Code Generation</h3>

<p>An unexpected discovery emerged: the workflow genesis system was stripping spacing between functions, making generated code hard to read. Investigation revealed the issue in <code class="language-plaintext highlighter-rouge">splice_workflow_step.py</code>:</p>

<p><strong>Root Cause</strong>: Insufficient newlines in template generation
<strong>Fix</strong>: Add proper spacing (<code class="language-plaintext highlighter-rouge">\n\n\n</code> instead of <code class="language-plaintext highlighter-rouge">\n\n</code>) in two key locations</p>

<p>This fix improved the developer experience for all future workflow generation.</p>

<h3 id="ui-modernization">UI Modernization</h3>

<p>The transplanted code still used hardcoded UI strings. The final step was modernizing these to use the centralized <code class="language-plaintext highlighter-rouge">self.ui</code> constants:</p>

<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Old way
</span><span class="n">Button</span><span class="p">(</span><span class="s">'Finalize 🔒'</span><span class="p">,</span> <span class="n">cls</span><span class="o">=</span><span class="s">'primary'</span><span class="p">)</span>

<span class="c1"># New way  
</span><span class="n">Button</span><span class="p">(</span><span class="bp">self</span><span class="p">.</span><span class="n">ui</span><span class="p">[</span><span class="s">'BUTTON_LABELS'</span><span class="p">][</span><span class="s">'FINALIZE'</span><span class="p">],</span> <span class="n">cls</span><span class="o">=</span><span class="bp">self</span><span class="p">.</span><span class="n">ui</span><span class="p">[</span><span class="s">'BUTTON_STYLES'</span><span class="p">][</span><span class="s">'PRIMARY'</span><span class="p">])</span>
</code></pre></div></div>

<h2 id="the-philosophical-dimension-human-ai-collaboration">The Philosophical Dimension: Human-AI Collaboration</h2>

<p>This rebuild became a case study in optimal human-AI collaboration. Like the deaf-and-blind duo in <em>See No Evil, Hear No Evil</em>, each partner compensated for the other’s limitations:</p>

<p><strong>AI Strengths:</strong></p>
<ul>
  <li>Pattern recognition and architectural analysis</li>
  <li>Debugging complex interconnected issues</li>
  <li>Documentation and explanation of problems</li>
  <li>Strategic planning and sequencing</li>
</ul>

<p><strong>Human Strengths:</strong></p>
<ul>
  <li>Precision copy/paste operations in sophisticated editors</li>
  <li>Understanding subtle code dependencies</li>
  <li>Making judgment calls about what to keep vs. replace</li>
  <li>Executing mechanical tasks that AI struggles with</li>
</ul>

<p><strong>The Result</strong>: A development process faster and more reliable than either partner could achieve alone.</p>

<h2 id="lessons-learned-template-based-development">Lessons Learned: Template-Based Development</h2>

<p>The Parameter Buster rebuild validated several key principles:</p>

<h3 id="1-templates--customization--pure-inheritance">1. Templates + Customization &gt; Pure Inheritance</h3>
<p>The template approach provided 80% of the infrastructure while allowing complete customization of the remaining 20%. This struck the right balance between DRY principles and workflow-specific flexibility.</p>

<h3 id="2-centralized-ui-constants-matter">2. Centralized UI Constants Matter</h3>
<p>Moving button labels, styles, and messages to <code class="language-plaintext highlighter-rouge">PIPULATE_CONFIG</code> made the entire system more maintainable and consistent.</p>

<h3 id="3-route-registration-patterns">3. Route Registration Patterns</h3>
<p>Template-based route registration works beautifully for standard patterns but requires careful handling of custom routes and registration timing.</p>

<h3 id="4-chain-reaction-reliability">4. Chain Reaction Reliability</h3>
<p>The explicit <code class="language-plaintext highlighter-rouge">hx-trigger="load"</code> pattern proved robust once properly implemented, providing clear debugging paths for workflow flow issues.</p>

<h3 id="5-code-generation-quality">5. Code Generation Quality</h3>
<p>Investing in proper spacing and formatting for generated code pays immediate dividends in developer experience.</p>

<h2 id="the-broader-impact">The Broader Impact</h2>

<p>This rebuild wasn’t just about Parameter Buster—it was about proving that the “polish the lenses” philosophy works. By investing in:</p>
<ul>
  <li>Helper scripts for workflow generation</li>
  <li>Templates that capture common patterns</li>
  <li>Centralized UI management</li>
  <li>Better debugging tools</li>
</ul>

<p>…the system reached a point where complex workflows could be built faster and more reliably than before.</p>

<p>The success here opened the door for rapid development of additional workflows like the Cosmograph Link Graph Visualizer and other D3-based visualization tools. The lens polishing was complete; now it was time to use the microscope.</p>

<h2 id="looking-forward-the-ai-development-revolution">Looking Forward: The AI Development Revolution</h2>

<p>This project exemplified something remarkable happening in software development: we’re not just using AI to write code, we’re developing hybrid intelligence workflows where human intuition and AI capability combine in unprecedented ways.</p>

<p>The future isn’t about AI replacing developers—it’s about developers becoming conductors of human-AI orchestras, each partner contributing their unique strengths to create software that neither could build alone.</p>

<p><strong>The Parameter Buster rebuild succeeded not because of AI or human skill alone, but because of the thoughtful integration of both.</strong> This may well be the template for how the most sophisticated software gets built in the age of AI: not by human or machine, but by human <em>and</em> machine, working in carefully choreographed harmony.</p>

<hr />

<p><em>The rebuilt Parameter Buster now sits in the system, a testament to this new way of building software—faster, cleaner, and more maintainable than what came before, ready to serve as the foundation for the next wave of analytical workflows.</em></p>

<hr />

<h2 id="from-refactoring-win-to-the-next-frontier-the-cosmograph-visualizer">From Refactoring Win to the Next Frontier: The Cosmograph Visualizer</h2>

<p>Pshwew! That was an adventure. These weekend deep dives always seem like the big
checklist delvierable item wasn’t done. I started out with a Parameter Buster. I
ended up with a Parameter Buster. However, with each passing project that does
one of these iterative sweeps, grinding and polishing the focal-lenses of
human-abstraction to AI-implementation, the more rapid the next and the next and
the next projects come into place.</p>

<p>Speaking of which, it’s still barely 2:00 PM on Sunday. And I have time left now
to slam out the big link graph visualizer, the one that lets you view hundreds
of thousands or even millions of edges of page-to-page links in your site.</p>

<hr />

<h2 id="book-analysis">Book Analysis</h2>

<p>Of course. Here is a multi-faceted analysis and transformation of the provided journal entry, structured to serve as foundational material for a future tech book.</p>

<hr />

<p><strong>Crafting Compelling Narratives: Title &amp; Filename Brainstorm:</strong></p>

<ul>
  <li><strong>Title Option 1:</strong> The Human as a Tool Call: A Case Study in Hybrid AI-Assisted Refactoring
    <ul>
      <li><strong>Filename:</strong> <code class="language-plaintext highlighter-rouge">hybrid-ai-assisted-refactoring-case-study.md</code></li>
      <li><strong>Rationale:</strong> This title highlights the most unique aspect of the entry—the novel development process. It appeals to readers interested in the future of software development, AI collaboration, and process philosophy.</li>
    </ul>
  </li>
  <li><strong>Title Option 2:</strong> The Great Transplant: Modernizing a Monolithic Plugin with a Template-Based System
    <ul>
      <li><strong>Filename:</strong> <code class="language-plaintext highlighter-rouge">modernizing-monolithic-plugin-transplant.md</code></li>
      <li><strong>Rationale:</strong> A strong, technically-focused title that clearly states the problem and solution. It uses the author’s own evocative term (“The Great Transplant”) and will attract engineers facing similar legacy code challenges.</li>
    </ul>
  </li>
  <li><strong>Title Option 3:</strong> Polishing the Lenses: How Iterative Refinement Unlocks Development Velocity
    <ul>
      <li><strong>Filename:</strong> <code class="language-plaintext highlighter-rouge">iterative-refinement-unlocks-velocity.md</code></li>
      <li><strong>Rationale:</strong> This title focuses on the philosophical underpinning of the work described. It’s perfect for a chapter on development methodology and appeals to senior developers, tech leads, and engineering managers.</li>
    </ul>
  </li>
  <li><strong>Preferred Option:</strong>
    <ul>
      <li><strong>Title (plain text for YAML):</strong> The Human as a Tool Call: A Case Study in Hybrid AI-Assisted Refactoring</li>
      <li><strong>Filename:</strong> <code class="language-plaintext highlighter-rouge">hybrid-ai-assisted-refactoring-case-study.md</code></li>
      <li><strong>Rationale:</strong> This title is the most distinctive and forward-looking. It captures the unique, sci-fi-like dynamic the author describes, turning a technical task into a compelling story about a new way of working. It has the broadest appeal while still being rooted in a concrete technical achievement.</li>
    </ul>
  </li>
</ul>

<p><strong>Book Potential Analysis:</strong></p>

<ul>
  <li><strong>Strengths as Book Fodder:</strong>
    <ul>
      <li><strong>Authenticity:</strong> It’s a raw, first-person account of a developer’s real-time thought process, complete with frustrations and philosophical asides—a perspective rarely seen in sanitized technical books.</li>
      <li><strong>Practical Case Study:</strong> It details a common and challenging software engineering task (refactoring a legacy component) with a clear problem, a novel methodology, and a defined outcome.</li>
      <li><strong>Illustrates a Philosophy:</strong> It provides a concrete example of the “WET Workflows” and “polish the lenses” philosophies, moving them from abstract concepts to applied practice.</li>
      <li><strong>Forward-Looking Process:</strong> It documents a sophisticated human-AI collaboration workflow that is highly relevant to the future of software development.</li>
    </ul>
  </li>
  <li><strong>Opportunities for Enrichment (for Book Adaptation):</strong>
    <ul>
      <li><strong>Add “Before &amp; After” Snippets:</strong> To make the value of the refactor concrete, include small, side-by-side code snippets showing how a piece of logic looked in <code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code> versus how it looks in the new <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code> after leveraging the <code class="language-plaintext highlighter-rouge">Pipulate</code> helpers.</li>
      <li><strong>Visualize the “Atomic Clumping”:</strong> Create a simple diagram (perhaps using Mermaid.js) that visually represents the strategy of grouping methods in the “prep” file before moving them. This would make the abstract concept tangible for the reader.</li>
      <li><strong>Create a “Key Takeaways” Box:</strong> Summarize 2-3 key lessons a reader could apply to their own refactoring or AI-collaboration projects, such as “Identify which tasks are best for human precision vs. AI planning” or “How to build a system of helpers that supports WET workflows.”</li>
    </ul>
  </li>
</ul>

<p><strong>AI Editorial Perspective: From Journal to Chapter:</strong>
This entry is an outstanding candidate for a chapter focused on <strong>Development Process as a Product</strong>. While the technical outcome is the refactoring of a plugin, the true story is about the <em>how</em>—the deliberate creation and application of a sophisticated, hybrid intelligence workflow. The narrative seamlessly connects high-level philosophy (the nature of AI’s arrival, the value of refinement) with low-level, practical execution (the specific <code class="language-plaintext highlighter-rouge">cp</code> command and the <code class="language-plaintext highlighter-rouge">nvim</code>-centric transplant strategy). This duality is exceptionally rare and valuable.</p>

<p>The raw, journal-style format is its greatest strength. When framed correctly, it provides an authentic “ride-along” experience, allowing the reader to inhabit the developer’s mindset. For a book, this entry could anchor a chapter titled “The AI-Augmented Developer” or “Pragmatic Refactoring in the Age of AI.” The key is to preserve the first-person voice and the “in-the-moment” discoveries while adding just enough structure (like the proposed subheadings and “Lessons Learned” boxes) to guide the reader through the technical and philosophical journey. It’s a powerful illustration of how to treat not just the code, but the <em>process of creating the code</em>, as a first-class citizen of software engineering.</p>

<p><strong>Suggested Next AI Processing Steps:</strong></p>

<ol>
  <li><strong>Task Suggestion 1:</strong> Elaborate on the “See No Evil, Hear No Evil” analogy.
    <ul>
      <li><strong>Potential Prompt Snippet for Next AI:</strong> “Based on the journal entry’s analogy of the developer and AI as the ‘deaf leading the blind’ from <em>See No Evil, Hear No Evil</em>, expand this into a full paragraph. Detail which role (human or AI) maps to which disability and why that mapping is a powerful metaphor for their complementary strengths and weaknesses in a software development context.”</li>
    </ul>
  </li>
  <li><strong>Task Suggestion 2:</strong> Formalize the transplant methodology.
    <ul>
      <li><strong>Potential Prompt Snippet for Next AI:</strong> “Analyze the described process of refactoring <code class="language-plaintext highlighter-rouge">110_parameter_buster.py</code> into <code class="language-plaintext highlighter-rouge">115_parameter_buster2.py</code>. Based on the steps taken (preparation, atomic grouping, transplantation, integration), draft a formal, step-by-step methodology named the ‘Atomic Transplant Pattern’. Present it as a reusable guide that other developers could follow for similar legacy code refactoring projects.”</li>
    </ul>
  </li>
</ol>

</div>
  <meta itemprop="url" content="https://mikelev.in/futureproof/hybrid-ai-assisted-refactoring-case-study/">
  <meta itemprop="mainEntityOfPage" content="https://mikelev.in/futureproof/hybrid-ai-assisted-refactoring-case-study/">
  <div itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
    <meta itemprop="name" content="AI SEO Mike Levin">
    <meta itemprop="url" content="https://mikelev.in">
    <div itemprop="logo" itemscope itemtype="https://schema.org/ImageObject">
      <meta itemprop="url" content="https://mikelev.in/assets/logo.png">
    </div>
  </div>
</article>
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "The Human as a Tool Call: A Case Study in Hybrid AI-Assisted Refactoring",
  "datePublished": "2025-06-08T00:00:00+00:00",
  "dateModified": "2025-06-08T00:00:00+00:00",
  "author": {
    "@type": "Person",
    "name": "Mike Levin"
  },
  "description": "This entry captures that specific, intense state of flow on a Sunday morning, where the path forward is finally clear. After wrestling with unexpected infras...",
  "url": "https://mikelev.in/futureproof/hybrid-ai-assisted-refactoring-case-study/",
  "abstract": "This entry captures that specific, intense state of flow on a Sunday morning, where the path forward is finally clear. After wrestling with unexpected infrastructure issues and taking the time to 'polish the lenses' of the system, the primary goal is now in sight: rebuilding the Parameter Buster plugin. The core of this moment is the conscious decision to adopt a specific, manual-first strategy for this complex code transplant, leveraging my own `nvim` skills as a precise 'tool' to avoid the common pitfalls of generative AI. This isn't just about the code; it's about defining a pragmatic, effective partnership with my AI assistant to tackle a difficult refactoring task.",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://mikelev.in/futureproof/hybrid-ai-assisted-refactoring-case-study/"
  },
  "publisher": {
    "@type": "Organization", 
    "name": "AI SEO Mike Levin",
    "logo": {
      "@type": "ImageObject",
      "url": "https://mikelev.in/assets/logo.png"
    }
  },
  "keywords": "",
  "wordCount": "5062"
}
</script>
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    
    
    {
      "@type": "ListItem",
      "position": 1,
      "name": "From Private to Public: A Practical Guide to Migrating Your GitHub Pages Repo",
      "item": "https://mikelev.in/futureproof/migrate-github-pages-private-public/"
    },
    
    
    {
      "@type": "ListItem", 
      "position": 2,
      "name": "Home",
      "item": "https://mikelev.in"
    }
    ,
    
    {
      "@type": "ListItem",
      "position": 3,
      "name": "The Perfect Pebble: A Minimalist's Guide to Igniting a Tech Movement",
      "item": "https://mikelev.in/futureproof/perfect-pebble-tech-movement-strategy/"
    }
    
  ]
}
</script>
<nav class="post-navigation bottom-nav" itemscope itemtype="https://schema.org/BreadcrumbList">
  
    <div class="previous-post" itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <span class="nav-label">Previous Post</span>
      <a href="https://mikelev.in/futureproof/migrate-github-pages-private-public/" itemprop="item">From Private to Public: A Practical Guide to Migrating Your GitHub Pages Repo</a>
      <meta itemprop="name" content="From Private to Public: A Practical Guide to Migrating Your GitHub Pages Repo">
      <meta itemprop="position" content="1" />
    </div>
  
  <div class="home-link" itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
    <a href="https://mikelev.in/" itemprop="item" class="home-link-container">
      <span class="home-text" itemprop="name">
        <span class="nav-label">Blog Index</span>
        <span class="home-word">Home</span>
      </span>
      <span class="home-hamster">
        <img src="/images/dancing-hamster.gif" alt="Dancing Hamster" width="60px" height="60px">
      </span>
    </a>
    <meta itemprop="position" content="2" />
  </div>
  
    <div class="next-post wiggle-prompt" itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <span class="nav-label">Next Post</span>
      <a href="https://mikelev.in/futureproof/perfect-pebble-tech-movement-strategy/" itemprop="item">The Perfect Pebble: A Minimalist's Guide to Igniting a Tech Movement</a>
      <meta itemprop="name" content="The Perfect Pebble: A Minimalist's Guide to Igniting a Tech Movement">
      <meta itemprop="position" content="3" />
    </div>
  
</nav>



<div class="post-counter" style="text-align: center; margin: 20px 0; font-style: italic;">
  <span>Post #304 of 318 - June 8, 2025</span>
</div>
<aside class="related-posts">
    <h2 id="related-articles">Related Articles</h2>
    <ul><li>
            <a href="https://mikelev.in/futureproof/adaptive-workflow-template-driven-ui/">The Adaptive Workflow: Building a Template-Driven UI</a>
            <div class="post-meta">
              <span class="post-date">June 16, 2025</span><span class="post-description"> - Learn to build dynamic, template-driven Python workflows where UI steps adapt to configuration, using a case study involving HTMX, Botify, and AI collaboration.</span><span class="debug-score" style="display: none;">(Score: 2)</span>
            </div>
          </li><li>
            <a href="https://mikelev.in/futureproof/workflow-factory-emergent-modularity/">The Workflow Factory: A Case Study in Emergent Modularity</a>
            <div class="post-meta">
              <span class="post-date">June 15, 2025</span><span class="post-description"> - A case study on refactoring a Python workflow engine from numbered to named steps, enabling a modular "workflow factory" with rearrangeable logic.</span><span class="debug-score" style="display: none;">(Score: 3)</span>
            </div>
          </li><li>
            <a href="https://mikelev.in/futureproof/taming-the-workflow-htmx-chain-reaction/">Taming the Workflow HTMX Chain Reaction</a>
            <div class="post-meta">
              <span class="post-date">June 15, 2025</span><span class="post-description"> - Debug Pipulate’s chain reaction to build the Quadfecta workflow with HTMX and deterministic tools.</span><span class="debug-score" style="display: none;">(Score: 2)</span>
            </div>
          </li><li>
            <a href="https://mikelev.in/futureproof/teaching-ai-model-context-protocol/">Teaching AI to Act: The Model Context Protocol Breakthrough</a>
            <div class="post-meta">
              <span class="post-date">June 12, 2025</span><span class="post-description"> - Discover MCP: Teach LLMs to trigger tool calls like cat facts, weaving results into local AI conversations for powerful agency.</span><span class="debug-score" style="display: none;">(Score: 2)</span>
            </div>
          </li><li>
            <a href="https://mikelev.in/futureproof/simon-says-make-mcp-call-local-llm-tools/">Simon Says Make MCP Tool-call: Teaching a Local LLM to Use Tools</a>
            <div class="post-meta">
              <span class="post-date">June 11, 2025</span><span class="post-description"> - A case study on implementing and adding observability to a local LLM tool-calling (MCP) system, moving from a rigid prototype to a flexible training widget.</span><span class="debug-score" style="display: none;">(Score: 2)</span>
            </div>
          </li></ul>
  </aside></div>

  <meta itemprop="url" content="https://mikelev.in/futureproof/migrate-github-pages-private-public/">
  <meta itemprop="mainEntityOfPage" content="https://mikelev.in/futureproof/migrate-github-pages-private-public/">
  <div itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
    <meta itemprop="name" content="AI SEO Mike Levin">
    <meta itemprop="url" content="https://mikelev.in">
    <div itemprop="logo" itemscope itemtype="https://schema.org/ImageObject">
      <meta itemprop="url" content="https://mikelev.in/assets/logo.png">
    </div>
  </div>
</article>

Simply copy the new code block and paste it into your _layouts/post.html file at the location indicated. Once you commit and push this change, every one of your blog posts will automatically feature a direct link to its own markdown source on GitHub.

Victory Lap: Giving Back to the Bots with Open-Source Links

Me: Done, and even tested on my local Jekyll server. But…

[mike@nixos:~/repos/MikeLev.in/_posts]$ git commit -am "Linking to the original pre-rendered mardkown from the Jekyll static site generator rendered pages from the _posts directory of the git repo."
[main 8256e9920] Linking to the original pre-rendered mardkown from the Jekyll static site generator rendered pages from the _posts directory of the git repo.
 1 file changed, 10 insertions(+), 1 deletion(-)

[mike@nixos:~/repos/MikeLev.in/_posts]$ git push
fatal: The current branch main has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin main

To have this happen automatically for branches without a tracking
upstream, see 'push.autoSetupRemote' in 'git help config'.

Gemini: Ah, you’ve encountered the final, expected little hiccup in this process. This is not an error but a direct consequence of wiping the history.

The Explanation

When you performed the history-wiping steps, you did the following:

Created a new local branch named main.
Deleted the old local main branch.
Force-pushed the new main branch to GitHub (git push -f origin main).

That force-push was a one-time “shout” that told GitHub, “Here is the new main branch, accept it unconditionally!” However, it did not create a formal tracking connection between your new local main branch and the new origin/main branch on GitHub.

So, your local Git doesn’t know that future pushes from main should automatically go to origin/main.

The Solution

The good news is that Git itself tells you the exact command to fix this and establish that connection permanently.

As your terminal output suggests, you just need to run:

git push --set-upstream origin main

Running this command will do two things:

Push your latest commit (the one adding the markdown source link).
Set the remote origin/main as the “upstream” tracking branch for your local main branch.

This is a one-time command. After you run it successfully, all your future pushes can go back to being a simple git push.

Me: Done! And that’s one of the biggest potential consequences little commands I’ve ever done. Can you imagine! Oh, please do. And put a bow-tie on this article, right back from my discovering Github actions were no longer working — between yesterday and today / diagnosing it to nothing being technically wrong to where we ended up.

Gemini: Of course. It’s been a remarkable and consequential 24 hours. What started as a simple bug hunt evolved into a strategic pivot on digital infrastructure. Here is the bow-tie for your article, a summary of the entire affair from start to finish.

The Bow-Tie: From Silent Failure to a Declaration of Independence

It’s hard to imagine that this entire saga, a cascade of high-stakes commands and strategic decisions, began less than a day ago with a simple, unnerving silence. A git push was sent, and the expected GitHub Action—the familiar, automated Jekyll build that breathes life into a static site—never arrived. The void where automation should have been was the first clue.

The initial diagnosis was a hunt for a technical ghost. Was GitHub Pages down? Was there a subtle syntax error in the _config.yml or the post’s front matter? Yet, even the simplest test push of a foo.md file failed to trigger a response. The machine, it seemed, wasn’t just broken; it was ignoring us completely.

The true culprit, as it turned out, wasn’t a bug in the code but a rule in the billing system. The Pro plan had expired, and with it, the privilege of serving a GitHub Pages site from a private repository. The system hadn’t broken; a paywall had simply gone up. This was the crossroads: recommit to the “Microsoft tax,” as you put it, or take the opportunity to pivot. The choice was made to embrace a more open, self-reliant philosophy, a “de-Microsoft-ification” of the setup.

But declaring independence is never as simple as flipping a switch. To make the MikeLev.in repository public, its long and storied private history had to be dealt with. This set off a cascade of precise, consequential operations:

The Digital Safe Deposit Box: First, a perfect, history-intact copy of the private repository had to be secured. The easy path, GitHub’s own importer tool, failed, blocked by the very authentication rules GitHub itself had instituted. The solution required generating a temporary Personal Access Token (PAT) and executing a flawless command-line mirror-clone—a professional-grade backup ensuring the past was safe before it was erased.
The Digital Purge: With the backup secured, it was time to clean house. A custom Python script was born, acting like a smart assistant with its own eyes. It meticulously scanned all 1,888 content files, cross-referencing them against 225 images. After a successful dry run, it “boldly and bravely” purged 74 unused images, slimming the repository down for its public debut.
The Point of No Return: Then came the climax—the most consequential “little command” of all. With git checkout --orphan main-fresh and a subsequent git push -f origin main, years of accumulated Git history were wiped from the public-facing repository in an instant. It was a digital fresh start, a single command that severed the project from its past, leaving only the clean, final state of the code in a single “Initial commit.”

The journey concluded with the satisfying finality of git push --set-upstream origin main, re-establishing a formal link between the newly reborn local branch and its GitHub counterpart. The site was live again, now free and public.

As a final, symbolic act—a victory lap—a new feature was added. A link, on every page, pointing back to the raw markdown source. It was a gift to the open web and the AI agents that learn from it, transforming what began as a forced retreat from a paid feature into a full-throated embrace of open-source principles.

In the end, what started with a failed Action finished with a profound declaration. It was a masterclass in how a minor annoyance can trigger a chain reaction, leading to a stronger, cleaner, and more philosophically aligned result. The entire process, a testament to taking control, one consequential command at a time.

Yup.

Book Analysis

Here is the requested analysis and transformation of your technical journal entry.

Crafting Compelling Narratives: Title & Filename Brainstorm:

Title Option 1: The Point of No Return: Wiping Git History for a Public Debut
- Filename: wiping-git-history-public-debut.md
- Rationale: This title is dramatic and compelling, highlighting the irreversible nature of the core technical action. It appeals to readers interested in high-stakes DevOps tasks and the story behind them.
Title Option 2: From Private to Public: A Practical Guide to Migrating Your GitHub Pages Repo
- Filename: migrate-github-pages-private-public.md
- Rationale: A straightforward, solution-oriented title that targets a specific user need. It’s highly searchable and promises a practical, step-by-step guide, making it very valuable for a book.
Title Option 3: Escaping the Tax: How a Broken Build Led to Digital Sovereignty
- Filename: github-broken-build-digital-sovereignty.md
- Rationale: This title focuses on the philosophical motivation behind the technical actions. It attracts readers interested in development culture, open-source advocacy, and the trend of moving away from centralized, paid platforms.
Title Option 4: The Orphan Branch Strategy: Safely Erasing a Repository’s Past
- Filename: git-orphan-branch-erase-history.md
- Rationale: This title puts the core technical pattern—the “orphan branch”—front and center. It is ideal for an audience looking to learn specific, advanced Git techniques and design patterns.
Preferred Option:
- Title (plain text for YAML): From Private to Public: A Practical Guide to Migrating Your GitHub Pages Repo
- Filename: migrate-github-pages-private-public.md
- Rationale: While less dramatic, this title is the most useful and discoverable for a book context. It clearly states the problem and the promised solution, making it an invaluable resource for readers facing the exact same challenge.

Book Potential Analysis:

Strengths as Book Fodder:
- Authentic Problem-Solving: It provides a transparent, blow-by-blow account of solving a real-world problem, from diagnosis to resolution, which is far more engaging than a sterile tutorial.
- High-Stakes, Practical Demonstration: The entry details powerful but dangerous Git commands (git checkout --orphan, git push -f) within a real-world context, complete with the necessary safety precautions (backups, dry runs).
- Human-AI Collaboration: It seamlessly integrates AI-generated code (the Python script) and explanations into a human-driven workflow, serving as an excellent case study for AI-augmented development.
- Integrated Tooling: It showcases a holistic approach, moving from Git commands to a Python utility script to editing Jekyll’s Liquid templates, all to serve a single, unified goal.
Opportunities for Enrichment (for Book Adaptation):
- Visual Aids: Add a simple diagram (e.g., using Mermaid.js) to visually explain the “orphan branch” concept—showing the old main branch with its history being detached and replaced by the new main with its single commit.
- “Safety Checklist” Box: Before presenting the history-wiping commands, insert a visually distinct “Safety Checklist” callout box that summarizes the prerequisites: “✓ Private backup confirmed,” “✓ Unused assets purged,” “✓ You understand this is irreversible.”
- Generalize the Principle: Create a “Key Takeaways” section that abstracts the lessons. For example: 1. Use billing changes as a catalyst for architectural review. 2. Automate pre-migration cleanup with scripts. 3. The “Orphan Branch” pattern is the standard for a clean-slate history reset.

AI Editorial Perspective: From Journal to Chapter:

This entry is a perfect gem for a tech book, precisely because of its raw, “in-the-moment” nature. It’s an ideal anchor for a chapter on “Pragmatic DevOps and Infrastructure Migration.” While many books present polished, after-the-fact solutions, this log captures the far more valuable process: the dawning realization of a problem, the articulation of a guiding philosophy (resisting the “Microsoft tax”), the necessary preparatory work (the image purge), and the satisfaction of a successful, high-stakes execution.

The human-AI dynamic is particularly noteworthy. The developer doesn’t just ask for a solution; they define a problem, request a specific tool, and then integrate that AI-generated tool into their larger, human-orchestrated plan. This elevates the narrative from a simple tutorial to a case study in “AI as a Collaborative Tool.” Curated with the subheadings and context suggested, this raw log transforms into a compelling and highly educational story that is more authentic and memorable than any textbook example could be.

Suggested Next AI Processing Steps:

Task Suggestion 1: Generate a Visual Explanation.
- Potential Prompt Snippet for Next AI: “Based on the attached case study about wiping Git history, generate a Mermaid.js ‘gitGraph’ diagram that visualizes the ‘orphan branch’ process. The ‘before’ state should show a main branch with multiple commits. The ‘after’ state should show the old main branch gone and a new main branch with only one ‘Initial commit’.”
Task Suggestion 2: Draft a “Lessons Learned” Section.
- Potential Prompt Snippet for Next AI: “Analyze the provided technical journal entry and synthesize the key technical and philosophical takeaways into a ‘Lessons Learned’ section for a book. Focus on three main areas: diagnosing deployment failures, safely executing destructive Git commands, and the strategic benefits of open-sourcing personal projects.”

From Private to Public: A Practical Guide to Migrating Your GitHub Pages Repo

Sunday, June 8, 2025

Setting the Stage: Context for the Curious Book Reader

A Push into the Void: Diagnosing a Silent Failure

The Culprit in the Invoice: A Philosophical Crossroads

Executing the Digital Reset: The Orphan Branch Strategy

A Final, Irreversible Push

The Strategy

Step-by-Step Guide to Wiping the Git History

Step 1: Navigate to Your Local Repository

Step 2: Create a New, Empty “Orphan” Branch

Step 3: Add and Commit All Your Current Files

Step 4: Delete the Old main Branch

Step 5: Rename Your New Branch to main

Step 6: Force-Push to GitHub

What to Expect After

Your Final Steps

The Purge Before the Plunge: Cleaning House with Python

How It Works

The Script: purge_unused_images.py

How to Use

Final Steps: Wiping History and Going Public

1. Create the New History

2. Replace the Old main Branch

3. Force-Push to GitHub

4. Make the Repository Public and Enable Pages

Exposing All My Markdown to LLMs For The Win!

The Strategy

The Code to Add

Victory Lap: Giving Back to the Bots with Open-Source Links

The Explanation

The Solution

The Bow-Tie: From Silent Failure to a Declaration of Independence

Book Analysis

Step 4: Delete the Old `main` Branch

Step 5: Rename Your New Branch to `main`

The Script: `purge_unused_images.py`

2. Replace the Old `main` Branch