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"
  });
}

1. 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
  });
}