Code Refinement Pipeline

I had never considered that there was specific codebase hygiene that needed adhering to until I went to demo one of my tools to a software engineer friend. He showed his demo first - his codebase was organised logically, he knew where everything was, it was tidy, everything made sense. I shared my codebase and got a little self-conscious. I had organically settled into having 15 .md files floating around the working tree, things hardcoded in random places, and a grep battle waiting for elements that were changed piece by piece rather than with a consistent rule.

I started developing a system to tidy the codebase - silly prompts like:

"If I showed this codebase to a 500 IQ software engineer what would their main criticisms be?"

"I'm preparing to present this tool to my CISO, what do you expect she'll say?"

"I've got our lead Software Architect reviewing my build in front of the engineering team next week, anything we should tidy up before then?"

To be fair, running prompts like that in a chain can be quite effective to clean up mess, but I wanted to systematise the concept in a repeatable way. A good refactor shouldn't just be beautiful, it should be logical, reduce bloat, and lay the groundwork for future development.

I've built a SKILL that runs four passes on a progressively cleaner codebase, each reading it through a different lens: a staff engineer's first impression of the structure, a scan for the patterns AI-assisted code tends to favour, and a maintainer working out what someone inheriting the codebase will lament.

You make the call on every change. Each is proposed with a recommendation you can take or override, applied one at a time as its own commit. It runs your build and tests as it goes and reverts anything that breaks it, so you're not hunting for a regression three changes later. I've run it on projects over 100k lines of code and on smaller ones around 5-10k; on the big ones it chunks the codebase and works the highest-impact sections first.

The SKILL is open source and MIT licensed. I'd love to hear your feedback: contact@henryguyver.com