Thoughtbox:refactor

Theseus Refactoring Protocol

Refactoring has a failure mode: scope creep. You start renaming one function and end up restructuring three modules. Theseus prevents this by locking your file scope upfront, requiring explicit justification to expand it, and tracking how often your changes break tests.

Core Mechanics

• Scope: declared file list at init — you can only touch these files
• Visa: explicit request to touch an out-of-scope file (requires justification)
• Checkpoint: submit each logical change for audit before proceeding
• B-counter: tracks test failures — high B means your refactor is causing breakage
• Terminal state: completed, abandoned, or rolled back

Workflow

Phase 1: Declare Scope

Identify every file you expect to touch. Be specific — this is your contract.

// thoughtbox_execute
async () => {
  return await tb.theseus({
    operation: "init",
    scope: ["src/auth/handler.ts", "src/auth/types.ts", "src/auth/middleware.ts"],
    description: "Extract token validation into standalone module"
  });
}

The session starts with B=0 (no test failures yet).

Phase 2: Work Within Scope

Make changes to declared files. After each logical unit of work:

1. Checkpoint the change:

async () => {
  return await tb.theseus({
    operation: "checkpoint",
    diffHash: "abc123",  // git diff hash or commit SHA
    commitMessage: "refactor(auth): extract TokenValidator class",
    approved: true,
    feedback: "Clean extraction, no behavior change"
  });
}

2. Run tests and record outcome:

async () => {
  return await tb.theseus({
    operation: "outcome",
    testsPassed: true,
    details: "All 47 auth tests pass"
  });
}

If tests fail, B increments. If B reaches 3, stop and reassess — your refactor is causing too much breakage.

Phase 3: Expand Scope (If Needed)

If you discover you need to touch a file outside your declared scope, request a visa:

async () => {
  return await tb.theseus({
    operation: "visa",
    filePath: "src/routes/login.ts",
    justification: "Login route imports TokenValidator directly — need to update import path",
    antiPatternAcknowledged: true
  });
}

Setting antiPatternAcknowledged: true is required — it forces you to recognize that scope expansion is a code smell. If you're requesting many visas, your initial scope was wrong.

Phase 4: Check Status

Monitor your session state anytime:

async () => {
  return await tb.theseus({ operation: "status" });
}
// Returns: B counter, scope list, visa count, audit count

Phase 5: Complete

async () => {
  return await tb.theseus({
    operation: "complete",
    terminalState: "completed",
    summary: "Extracted TokenValidator into src/auth/token-validator.ts. 3 files changed, 1 visa (login route import). B=0."
  });
}

Terminal states: "completed", "abandoned", "rolled_back"

Discipline Rules

When NOT to Use Theseus

• Adding new features (use regular development workflow)
• Bug fixes (use thoughtbox:debug / Ulysses instead)
• One-file changes (overkill — just make the change)
• Exploratory prototyping (scope locking kills exploration)