banthis

Banthis — durable behavioral bans

Extend the local instruction surface with a named prohibition. The op-cell is extend: add one hard rule, keep existing project memory intact, and make the rule visible to future sessions.

Banthis is for user frustration or correction that should persist. It is not a notes system, preference logger, or policy engine.

---

When to Apply

Apply immediately when the user signals a behavior should never recur:

• “stop doing X”
• “never do that again”
• “ban this”
• “remember not to …”
• “add a project rule …”
• repeated frustration with a specific agent behavior

Certainty:

• HIGH — explicit ban language or direct instruction to remember a prohibition.
• MEDIUM — frustration plus a concrete repeated behavior. Ask only if the rule boundary is ambiguous.
• LOW — stylistic preference, local task constraint, or one-off correction. Do not persist unless the user asks.

---

When NOT

Do not write a ban when:

• the constraint applies only to the current command or current file;
• the request is a normal implementation requirement;
• the rule would be vague (“be better”, “stop being annoying”);
• the rule duplicates an existing ban with no stronger wording;
• the rule is unsafe, impossible, or conflicts with a higher-priority instruction.

If a requested ban conflicts with an existing ban, surface the conflict instead of rewriting history.

---

Workflow

1. Extract the invariant. Identify the forbidden behavior and the reason. No moralizing.

2. Craft the title. <60 characters, noun phrase or imperative fragment, no markdown markers.

   • Good: No silent scope shrink
   • Bad: User got mad because we keep doing dumb partial work

3. Craft the rule. One line, direct prohibition, reason included:

   • Do not X — reason.

4. Choose scope.

   • Project-specific behavior: omit --global.
   • Agent-wide verbal tic or repeated generic habit: add --global.

5. Write through the managed command. From the skill directory, run:

   node scripts/banthis.mjs add "<title>" "Do not X — reason."
   

   For user-wide bans:

   node scripts/banthis.mjs --global add "<title>" "Do not X — reason."
   

6. Report minimally. Say which target file received the ban and whether it was added, updated, or unchanged.

---

Target resolution

The script resolves the write target deterministically:

1. --global always writes ~/.claude/CLAUDE.md.
2. Otherwise, use the current working directory.
3. In the current directory, AGENTS.md takes precedence over CLAUDE.md.
4. If neither exists, create CLAUDE.md.

No repository scan. No editor adapter. No external binary.

---

Managed-section invariant

The script owns only this range:

<!-- banthis:start -->
...
<!-- banthis:end -->

Guardrails:

• Never hand-edit inside the markers when the command can do it.
• Never place user-supplied text containing banthis markers into a title or rule.
• If the managed section exists, replace only that byte range.
• If absent, insert after the first top-level # H1; if no H1 exists, prepend the section.
• Preserve every byte outside the managed range except the minimal insertion boundary.

The managed section contains a preamble asserting that bans win over the current request. Future sessions must surface conflicts instead of quietly violating bans.

---

Command contract

node scripts/banthis.mjs add <title> <rule>
node scripts/banthis.mjs list
node scripts/banthis.mjs remove <title>
node scripts/banthis.mjs init

Shortcut:

node scripts/banthis.mjs <title> <rule>

Flags:

-g, --global   target ~/.claude/CLAUDE.md
-h, --help     print usage

Results:

• added — no case-insensitive title match existed.
• updated — title matched case-insensitively and title or rule changed.
• unchanged — exact title and rule already present.

---

Anti-patterns

• Excess — storing every preference as a hard ban. Bans are scarce and sharp.
• Graft — adding a second memory mechanism, JSON cache, slash-command shim, or editor adapter.
• Sprawl — scanning parent directories or rewriting unrelated docs.
• Soft ban — phrasing as “try not to” or “prefer not to”. Use Do not … — reason.
• Hidden conflict — obeying the current request while violating a persisted prohibition.

---

Validation Gates

Before yielding after a ban operation:

1. The target file contains exactly one <!-- banthis:start --> and one <!-- banthis:end --> pair.
2. The new or updated title appears once, case-insensitive.
3. The rule is one line and starts with Do not unless the user supplied a stronger exact wording.
4. Content outside the managed markers is unchanged except for first insertion.
5. list reports the expected title and rule preview.