The Great Refactor: Six Weeks in Eighteen Days

October 7, 2025

Tuesday morning at 7:04 AM, my Chief Architect began planning GREAT-4F — the final piece of intent classification. Improve classifier accuracy to 95%+, document the canonical handler pattern, establish quality gates protecting everything we’d built.

One epic remaining after that: GREAT-5, the validation suite that would lock in all achievements from GREAT-1 through GREAT-4.

By 6:52 PM, both were complete.

At 7:01 PM, Chief Architect confirmed: “CORE-GREAT ready to close — all 5 GREAT epics complete.”

September 20 to October 7. Eighteen days. Five major epics estimated at six weeks or more. Production-ready foundation with 142+ tests, 100% passing, comprehensive quality gates operational.

The pause the precipitated this effort came from one of my lowest points on this project, my I sincerely wondered if this had all been a fascinating waste of my time. Now less than three weeks later I feel more confident than ever that I’m building something real.

This is the story of how Tuesday brought another milestone for what four months of systematic work had built toward. Not through heroic effort, but through discovering that most of the work had already been done — it just needed the final 5% found, fixed, and validated.

The two-minute ADR

At 7:51 AM, Code agent deployed to create ADR-039: Canonical Handler Pattern documentation. Estimated time: 20–30 minutes. Actual time: 2 minutes. Why do they pad these estimates? They know they write fast, right?

The ADR wasn’t shorter or lower quality than expected. It was comprehensive: 399 lines documenting the dual-path architecture, explaining when to use canonical handlers versus workflow orchestration, including performance metrics from GREAT-4E, providing troubleshooting guidance.

What made it fast wasn’t the agent writing faster. It was the specification being clearer.

The gameplan didn’t say “write an ADR about canonical handlers.” It said:

Document the dual-path architecture: WHAT (two routing paths exist), WHY (performance vs capability trade-offs), WHEN (which path for which requests), HOW (decision criteria), PERFORMANCE (actual metrics from GREAT-4E benchmarks).

Clear specifications enable speed. When the agent knows exactly what “done” looks like, implementation becomes straightforward.

This pattern repeated throughout Tuesday.

Phase 1 (QUERY fallback patterns): estimated 30–40 minutes, actual 14 minutes. GREAT-5 Phase 3 (integration tests): estimated 45–60 minutes, actual 15 minutes.

Not because work was skipped. Because foundations were solid and requirements were clear.

The missing definitions

At 9:40 AM, Cursor completed Phase 2 of GREAT-4F: enhancing the LLM classifier prompts.

The discovery was almost embarrassing in its simplicity.

The classifier prompt didn’t include definitions for the five canonical categories. This feels like the kind of shortcut/oversight that plagued our coding process for most of the first few months.

The categories existed. The handlers worked. The routing was correct. The tests all passed. But the LLM classifier — the system that decides which category a natural language query belongs to — had never been told what the canonical categories actually were.

When someone said “What day is it?” the classifier would see:

Available categories: QUERY, CREATE, UPDATE, SEARCH, EXECUTION, ANALYSIS, SYNTHESIS, STRATEGY, LEARNING, GUIDANCE, UNKNOWN
Query: “What day is it?”
Decision: Probably QUERY (default when unsure)

TEMPORAL didn’t appear in the options because the prompt never mentioned it existed.

The fix: Add five lines defining canonical categories in the classifier prompt.

The impact: +11 to 15 percentage points accuracy improvement.

PRIORITY went from 85–95% accuracy to 100% (perfect classification). TEMPORAL jumped to 96.7%. STATUS to 96.7%. All three exceeding the 95% target.

It’s a weird feeling to be both annoyed that something so simple was skipped and hiding in plain site as well as relieved and satisfied after fixing it.

This is the flip side of the “75% pattern.” Sometimes you discover infrastructure is better than expected. Sometimes you discover a simple fix dramatically improves things. But both require actually looking.

The categories worked in isolation. Unit tests passed. Integration tests with canonical queries worked because those tests bypassed the LLM classifier entirely — they called handlers directly.

The gap only appeared when testing the full flow: natural language → LLM classification → canonical handler routing.

Comprehensive testing reveals assumptions. And sometimes those assumptions are “surely someone told the classifier what these categories mean.”

The permissive test anti-pattern

Throughout Tuesday morning, a pattern kept appearing in the test suite:

# Permissive (accepts both success and failure):
assert response.status_code in [200, 404]

# Strict (requires success):
assert response.status_code == 200

The permissive version accepts both “working correctly” (200) and “endpoint doesn’t exist” (404) as valid test passes. When I saw that I was like “wait, wat?” How is “endpoint doesn’t exist” a success state? Because a reply was returned? Come on!

GREAT-5 Phase 1 systematically eliminated this pattern. Twelve permissive assertions replaced with strict requirements. The immediate result: tests started failing.

Good!

The failures revealed:

IntentService initialization errors: Test fixtures weren’t properly setting up the service
Two cache endpoint bugs: AttributeError exceptions in production code
Health endpoint protection gaps: Tests accepting failures that would break monitoring

None of these were caught by permissive tests because permissive tests don’t catch problems — they hide them. Seriously, who writes permissive tests anyhow? Who trained the LLMs to do that?

The philosophy difference:

“Make tests pass”: Write tests that accept current behavior, even if broken
“Make code work”: Write strict tests that force code to meet requirements

Permissive tests create false confidence. Everything appears to work because tests pass. But the tests are lying — they pass whether code works or not.

By end of Phase 1, all permissive patterns were eliminated. Tests now enforce actual requirements. Which meant Phase 1 also had to fix the code that failed strict tests — including two production bugs that had been lurking undetected.

This is the unglamorous side of quality work. It’s not adding features. It’s making tests honest about what they validate.

Quality gates as compound momentum

GREAT-5’s goal was establishing additional quality gates protecting all GREAT-1 through GREAT-4 achievements. The existing gates were:

Intent classification tests
Performance regression detection
Coverage enforcement (80%+)
Bypass detection
Contract validation

To this we were now adding:

Zero-tolerance regression suite: Critical infrastructure must work, no exceptions
Integration test coverage: All 13 intent categories validated end-to-end
Performance benchmarks: Lock in 602K req/sec baseline from GREAT-4E
CI/CD pipeline verification: 2.5-minute runtime with fail-fast design

The interesting discovery: most of these already existed.

CI/CD pipeline? Already excellent, needed zero changes. Performance benchmarks? GREAT-4E had validated them, just needed test suite integration. Load testing? Cache validation tests already proved efficiency.

What remained was:

Enhancing regression tests with strict assertions
Creating comprehensive integration tests
Fixing the bugs strict tests revealed
Documenting what quality gates exist and why

GREAT-5 took 1.8 hours (109 minutes of actual work). Not because the work was small, but because foundations were already solid.

This is compound momentum visible: each previous epic made this one easier. GREAT-4E’s performance validation became GREAT-5’s benchmark baseline. GREAT-3’s plugin architecture became GREAT-5’s integration test framework. GREAT-2’s spatial intelligence became GREAT-5’s multi-interface validation.

Nothing built in isolation. Everything building on everything else.

The completion moment

At 1:15 PM, Chief Architect declared GREAT-4 complete.

All six sub-epics (4A through 4F) finished. Intent classification system production-ready:

13/13 categories fully implemented
95%+ accuracy for core categories
142+ query variants tested
Zero timeout errors through graceful fallback
Sub-millisecond canonical response time
84.6% cache hit rate with 7.6× speedup

By 6:52 PM, GREAT-5 was complete as well:

37 tests in comprehensive quality gate suite
Zero-tolerance regression protection
Performance baseline locked at 602K req/sec
All 13 intent categories validated through all interfaces
CI/CD pipeline verified operational

Completing an entire fifth epic after finishing the last several issues in the previous epic seems like a leap, but GREAT-5 is about locking down the work of the earlier epics, and it benefited greatly from all the cleanup work that preceded it.

At 7:01 PM, Chief Architect closed CORE-GREAT: “All 5 GREAT epics complete.”

The timeline:

GREAT-1 (Orchestration Core): September 20–27
GREAT-2 (Integration Cleanup): September 28 — October 1
GREAT-3 (Plugin Architecture): October 2–4
GREAT-4 (Intent Universal): October 5–7
GREAT-5 (Quality Gates): October 7

Total: 18 days from start to production-ready foundation. When the Chief Architect scoped this at six to seven weeks I was hoping (and to be honest, expecting) that it would not take quite that long, but this far exceeded my expectations.

What six weeks in eighteen days means

I’m not really talking about working faster and definitely not about cutting corners. This is about systematic work revealing that foundations were stronger than expected.

The pattern across all five epics:

Phase −1 verification consistently found infrastructure better than assumed. Two-layer caching already operational. Spatial intelligence already integrated. Plugin patterns already proven. Each epic started further along than the gameplan estimated.

The 75% pattern appeared repeatedly. Categories implemented, patterns missing. Handlers exist, definitions missing. Tests passing, strictness missing. The missing 25% wasn’t architecture — it was enumeration, documentation, and validation.

Compound momentum made each epic faster. GREAT-1’s orchestration patterns became GREAT-4’s intent routing. GREAT-2’s integration cleanup became GREAT-3’s plugin foundation. GREAT-3’s plugin architecture became GREAT-4’s category handlers.

Autonomous agent work accelerated when patterns were clear. The 2-minute ADR. The 14-minute QUERY fallback. The 15-minute integration test suite. Not because agents write faster, but because specifications were clearer and foundations were proven.

Independent validation caught what automated testing missed. The 69% thinking it’s 100% moment. The missing classifier definitions. The permissive test anti-pattern. Systematic verification refusing to accept “appears complete” without proving “actually complete.”

None of these are silver bullets. Each requires the others to work.

Clear specifications without solid foundations: agents build the wrong thing quickly
Solid foundations without verification: incomplete work ships thinking it’s complete
Verification without clear quality standards: you catch problems but don’t know what “good” looks like.

The methodology is the integration of all these pieces. And it took four months of development to get here — this isn’t where we started, it’s what we built toward.

The calm of completion

Tuesday evening feels different from Monday evening, which felt different from Sunday evening.

Sunday: Exhilaration of pattern coverage jumping 24% → 92% in fifteen minutes.

Monday: Relief that autonomous agent work validated correctly and scope gaps were caught.

Tuesday: Calm. Centered. Relaxed!

Not the calm before something. The calm of arriving. The foundation work is complete. The refactoring is done. The quality gates are operational. The tests all pass.

What comes next is building on this foundation, not replacing it.

We made issues for some of the items we postponed as somewhat out of scope: MVP-ERROR-STANDARDS will standardize error handling. CORE-TEST-CACHE will fix a minor test environment issue. CORE-INTENT-ENHANCE will optimize IDENTITY and GUIDANCE accuracy when it becomes important.

But none of those are GREAT epics. They’re incremental improvements to a foundation that’s already solid. This isn’t the end. It isn’t even the beginning of the end, to coin a phrase, but it might be the end of the beginning.

The Great Refactor is complete. Five epics, eighteen days, production-ready foundation. Achieved without heroic effort or accepting technical debt or cutting corners to ship faster.

Through systematic work discovering that the infrastructure was better than we thought, enumerating what remained, and validating that it all held together.

The methodology working exactly as designed.

Which is, for the third time this week, far more satisfying than dramatic rescues.

What this enables

With GREAT-1 through GREAT-5 complete, Piper Morgan now has:

Orchestration: Workflow factory coordinating all complex operations

Integration: Clean plugin architecture for all external services

Classification: Universal intent system routing all natural language

Performance: Sub-millisecond canonical handlers, 602K req/sec sustained

Quality: Comprehensive gates protecting all critical paths

The foundation enables alpha release to real users. Multi-user support operational. Spatial intelligence providing context-appropriate responses. Quality gates preventing regression. Performance validated under load.

Everything that comes next builds on this. Not replacing it, not refactoring it again, not discovering it was wrong. Just building the features that this foundation enables.

That’s what eighteen days of systematic work delivered. Not just working software, but a foundation trustworthy enough to build on without constantly looking over your shoulder wondering if it’ll collapse.

The calm of completion is knowing the foundation holds.