# Refactor Guarded

> Lightweight speed-bump for refactors that match the rejected-refactors list in AGENTS.md (Samsinn project). Greps for known-rejected patterns; on match, prints a one-line warning with line-pointer into AGENTS.md. NOT a gate — does not block, does not require justification. Just a friction reminder so future Codex sessions don't silently re-propose rejected work. Trigger keywords:/refactor, "refactor", "extract", "split createSystem", "replace lateBinding", "event bus", "consolidate", "MCP/REST parity", "artifact system". Use when this capability is needed.

- Skill: `tomevault-io/refactor-guarded` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/refactor-guarded`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/refactor-guarded/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/refactor-guarded

---


# Refactor Speed-Bump

> **First-time setup:** project-local skills are loaded at Codex session start. If this skill doesn't fire on rejected-pattern keywords right after pulling this repo, **restart Codex** to register.

Lightweight pattern check before proposing or implementing a refactor. Encodes the discipline of AGENTS.md's `## Rejected refactors` section so it survives across sessions.

## What this skill does

1. Match the user's refactor request against rejected patterns. The patterns:
   - "replace lateBinding" / "event bus" / "pub/sub for system"
   - "extract createSystem" / "split createSystem into phases" / "boot phase functions"
   - "MCP/REST parity" / "tool surface unification" / "audit MCP vs REST tools"
   - "revive artifacts" / "artifact system" / "workspace pane" / "task list pane" / "polls" / "shared documents"
2. On match, print a one-line warning with the file/line of the rejection in AGENTS.md.
3. Suggest: "If you have new evidence (a real bug, a second consumer, a measurable benefit), invoke `Codex-toolbox:stress-test` to evaluate. Otherwise, leave it alone."

## What this skill does NOT do

- Does NOT block the refactor. The user can override.
- Does NOT require written justification.
- Does NOT log the override.
- Does NOT critique the refactor on its merits (that's stress-test's job).
- Does NOT cover refactors not on the rejected list (those proceed normally).

## Implementation

Read `AGENTS.md`, locate the `## Rejected refactors` section. For each bullet:
- Extract the headline phrase (e.g. "Replacing `lateBinding` in `main.ts` with an event bus").
- Match the user's request against the headline + body keywords.

Print:

```
⚠️  This refactor matches a rejected pattern in AGENTS.md:36+

   "<headline of the matched bullet>"

   Per AGENTS.md: revisit only if you can demonstrate a *significant* new
   benefit (a bug traced to the pattern, a second-consumer use case, a
   measurable performance/correctness gain).

   If you have such evidence: run `Codex-toolbox:stress-test` next.
   Otherwise: leave this alone.
```

Then continue with normal flow. The user decides whether to proceed.

## Why a speed-bump and not a gate

The rejected list is human judgment, not algorithmic. A gate that demanded written justification would either:
- get rubber-stamped (everyone clicks "yes I have evidence" without thinking), or
- become bureaucracy that gets bypassed.

A one-line warning with a AGENTS.md pointer forces a 5-second pause and re-read. That's enough for an honest "oh right, that's why" without becoming friction theater.

---
> Source: [michaelhil/samsinn](https://github.com/michaelhil/samsinn) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->