Refactoring with Intent¶

Human-Guided Sessions in AI Development¶

Jose Alekhinne / 2026-02-01

This is the story of what happened when I stopped auto-accepting everything and started guiding the AI with intent. The result: 27 commits across 4 days, a major version release, and lessons that apply far beyond ctx.

The Velocity Trap¶

In the previous post, I documented the YOLO mode that birthed ctx: auto-accept everything, let the AI run free, ship features fast. It worked: until it didn't.

The codebase had accumulated patterns I didn't notice during the sprint:

I didn't see these during YOLO mode because, honestly, I wasn't looking.

Auto-accept means auto-ignore.

In YOLO mode, every file you open looks fine until you try to change it.

In contrast, refactoring mode is when you start paying attention to that hidden friction.

The Shift: From Velocity to Intent¶

On January 28^th, I changed the workflow:

1. Read every diff before accepting
2. Ask "why this way?" before committing
3. Document patterns, not just features

The first commit of this era was telling:

feat: add structured attributes to context-update XML format

Not a new feature—a refinement:

The XML format for context updates needed type and timestamp attributes.

YOLO mode would have shipped something that worked. Intentional mode asked:
"What does well-structured look like?"

The Decomposition: embed.go¶

The most satisfying refactor was splitting internal/claude/embed.go.

Before: One 153-line file doing five things:

• Command registration
• Hook generation
• Permission handling
• Script templates
• Type definitions

After: Five focused modules:

The refactor also renamed functions to follow Go conventions:

// Before: unnecessary prefixes
GetAutoSaveScript()
GetBlockNonPathCtxScript()
ListCommands()
CreateDefaultHooks()

// After: idiomatic Go
AutoSaveScript()
BlockNonPathCtxScript()
Commands()
DefaultHooks()

This wasn't about character count. It was about teaching the AI what good Go looks like in this project.

The next time it generates code, it has better examples to learn from.

The Documentation Debt¶

YOLO mode created features. It didn't create documentation standards.

The January 29^th sessions focused on standardization.

Terminology Fixes¶

• "context-update" → "entry" (what users actually call them)
• Consistent naming across CLI, docs, and code comments

Go Docstrings¶

// Before: inconsistent or missing
func Parse(s string) Entry { ... }

// After: standardized sections

// Parse extracts an entry from a markdown string.
//
// Parameters:
//   - s: The markdown string to parse
//
// Returns:
//   - Entry with populated fields, or zero value if parsing fails
func Parse(s string) Entry { ... }

This is intentionally more structured than typical GoDoc: It serves as documentation and as training data for future AI-generated code.

CLI Output Convention¶

All CLI output follows: [emoji] [Title]: [message]

Examples:
  ✓ Decision added: Use symbolic types for entry categories
  ⚠ Warning: No tasks found
  ✗ Error: File not found

A consistent output shape makes both human scanning and AI reasoning more reliable.

These aren't exciting commits. But they are force multipliers:

Every future AI session now has better examples to follow.

The Journal System¶

If you only read one section, read this one:

This is where v0.2.0 becomes more than a refactor.

The biggest feature of this change window wasn't a refactor—it was the journal system.

The journal system includes:

...and the meta continues: this blog post was generated using /ctx-blog.

The session history from January 28–31 was

• exported,
• enriched,
• and synthesized

into the narrative you are reading.

The Constants Consolidation¶

The final refactoring session addressed the remaining magic strings:

const (
    // Comment markers
    CommentOpen  = "<!--"
    CommentClose = "-->"

    // Index markers
    MarkerIndexStart = "<!-- INDEX:START -->"
    MarkerIndexEnd   = "<!-- INDEX:END -->"

    // Newlines
    NewlineLF   = "\n"
    NewlineCRLF = "\r\n"
)

The work also introduced thread safety in the recall parser and centralized shared validation logic; removing duplication that had quietly spread during YOLO mode.

I (Re)learned My Lessons¶

Similar to what I've learned in the former human-assisted refactoring post, this journey also made me realize that "AI-only code generation" isn't sustainable in the long term.

1. Velocity and Quality Aren't Opposites¶

YOLO mode has its place: for prototyping, exploration, and discovery.

BUT (and it's a huge "but"), it needs to be followed by consolidation sessions.

The ratio that worked for me: 3:1.

• Three YOLO sessions create enough surface area to reveal patterns;
• the fourth session turns those patterns into structure.

2. Documentation IS Code¶

When I standardized docstrings, I wasn't just writing docs. I was training future AI sessions.

Every example of good code becomes a template for generated code.

3. Decomposition > Deletion¶

When embed.go became unwieldy, the temptation was to remove functionality.

The right answer was decomposition:

• Same functionality
• Better organization
• Easier to test
• Easier to extend

The result: more lines overall, but dramatically better structure.

4. Meta-Tools Pay Dividends¶

The journal system took almost a full day to implement.

Yet it paid for itself immediately:

• This blog post was generated from session history
• Future posts will be easier
• The archaeological record is now browsable, not just grep-able

The Release: v0.2.0¶

The refactoring window culminated in the v0.2.0 release.

What's in v0.2.0:

The version bump was symbolic.

The real change was how the codebase felt.

Opening files no longer triggered the familiar "ugh, I need to clean this up" reaction.

The Meta Continues¶

This post was written using the tools built during this refactoring window:

1. Session history exported via ctx recall export
2. Journal entries enriched via /ctx-journal-enrich
3. Blog draft generated via /ctx-blog
4. Final editing done (by yours truly), with full project context loaded

Schedule both, or you'll only get one, if you're lucky.

This blog post was generated with the help of ctx, using session history, decision logs, learning logs, and git history from the refactoring window. The meta continues.