Clanker Discipline

by gbasin6d933da34627No license22 starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 6 months ago

Catches state bloat, grab-bag models, and mutation ambiguity from AI coding agents. Use when reviewing state types, boolean flags, optional-field models, or mutable data patterns.

Instructions onlySoftware Development

AI-generated overview

Reviews and refactors application state types, data models and state-handling functions to remove bloat and ambiguity.

What it does: Provides a set of coding rules for writing and reviewing state types, data models and functions that manage application state. It covers deriving values instead of storing flags, using discriminated unions and null over sentinels, encapsulating mutable state, enforcing mutation contracts, and replacing if-chains with lookup tables. It produces refactored code and a review checklist, with before-and-after TypeScript examples.
When to use it: Use it when reviewing or writing state types, boolean flags, optional-field models or mutable data patterns. It is meant to catch state bloat, grab-bag models and mutation ambiguity introduced by AI coding agents before the code lands.
Requirements: No scripts or tooling; it is an instructions-only document. The examples are TypeScript, but no runtime, package or credential is required.

Clanker Discipline

Apply these rules when writing or reviewing state types, data models, and functions that manage application state. Agents tend to add flags, optional fields, and special cases that compound into state nobody intended — catch that before it lands.

When you find violations, refactor fully. The goal is clean, maintainable code, not minimal diffs. Rip out the flags, reshape the types, restructure the functions. A bigger diff now is better than layering workarounds that compound later.

1. Derive, don't store

Every boolean you add doubles the theoretical state space. When a value can be derived from data you already have, do not store it. The best source to derive from is an event stream: a log of what happened.

Before: cached flags

An agent was asked to show a footer only when the assistant finishes naturally. It invented four flags:

type ThreadState = {  wasInterrupted: boolean;  didAssistantFinish: boolean;  didAssistantError: boolean;  wasToolCallOnly: boolean;};
function shouldShowFooter(state: ThreadState): boolean {  return state.didAssistantFinish    && !state.wasInterrupted    && !state.didAssistantError    && !state.wasToolCallOnly;}

type ThreadState = {  wasInterrupted: boolean;  didAssistantFinish: boolean;  didAssistantError: boolean;  wasToolCallOnly: boolean;};
function shouldShowFooter(state: ThreadState): boolean {  return state.didAssistantFinish    && !state.wasInterrupted    && !state.didAssistantError    && !state.wasToolCallOnly;}

Four fields to answer one question, with four mutation sites elsewhere keeping them in sync.

After: derive from evidence

function shouldShowFooter(events: SessionEvent[]): boolean {  const latest = getLatestAssistantMessage(events);  if (!latest) return false;  return latest.completed && !latest.error && latest.finish !== 'tool-calls';}

function shouldShowFooter(events: SessionEvent[]): boolean {  const latest = getLatestAssistantMessage(events);  if (!latest) return false;  return latest.completed && !latest.error && latest.finish !== 'tool-calls';}

The answer is now computed from events that already exist.

When NOT to derive

The domain genuinely has a state machine with ordered transitions. A checkout step is not a cached conclusion; it IS the state.
A field contains temporal or external data that cannot be rederived (timestamps from async processes, API responses needed downstream).
The derivation would be more complex than the stored value.

If you cannot derive, encapsulate

If mutable state must exist, trap it in the smallest possible scope. A closure is better than a class field:

// Bad: state visible to the whole classclass Writer {  private debounceTimeout: ReturnType<typeof setTimeout> | null = null;  queueSend(text: string) { /* can touch debounceTimeout */ }  flushNow() { /* can touch debounceTimeout */ }  somethingElse() { /* can also touch debounceTimeout */ }}
// Good: state trapped in a closurefunction createDebouncedAction(callback: () => void, delayMs = 300) {  let timeout: ReturnType<typeof setTimeout> | null = null;  return {    trigger() {      clearTimeout(timeout!);      timeout = setTimeout(() => { timeout = null; callback(); }, delayMs);    },    clear() {      if (timeout) { clearTimeout(timeout); timeout = null; }    },  };}

// Bad: state visible to the whole classclass Writer {  private debounceTimeout: ReturnType<typeof setTimeout> | null = null;  queueSend(text: string) { /* can touch debounceTimeout */ }  flushNow() { /* can touch debounceTimeout */ }  somethingElse() { /* can also touch debounceTimeout */ }}
// Good: state trapped in a closurefunction createDebouncedAction(callback: () => void, delayMs = 300) {  let timeout: ReturnType<typeof setTimeout> | null = null;  return {    trigger() {      clearTimeout(timeout!);      timeout = setTimeout(() => { timeout = null; callback(); }, delayMs);    },    clear() {      if (timeout) { clearTimeout(timeout); timeout = null; }    },  };}

Nothing outside the closure can touch the timer.

The debugging payoff

When state is derived from evidence, debugging becomes data-in, answer-out:

test('footer is hidden for aborted runs', () => {  const events = loadEvents('./fixtures/aborted-session.jsonl');  expect(shouldShowFooter(events)).toBe(false);});

test('footer is hidden for aborted runs', () => {  const events = loadEvents('./fixtures/aborted-session.jsonl');  expect(shouldShowFooter(events)).toBe(false);});

No mocking or timing reproduction. The bug is in the events or in the pure function.

2. Make wrong states impossible

Every optional field is a question the rest of the codebase must answer every time it touches that data.

Discriminated unions over optional bags

// Bad: when status is 'idle', should gateway/transactionId exist? The type doesn't say.type PaymentState = {  status: 'idle' | 'processing' | 'settled';  gateway?: 'stripe' | 'paypal';  transactionId?: string;  initiatedAt?: string;  settledAt?: string;};
// Good: each status carries exactly the fields it needs.type PaymentState =  | { status: 'idle' }  | { status: 'processing'; gateway: 'stripe' | 'paypal'; transactionId: string; initiatedAt: string }  | { status: 'settled'; gateway: 'stripe' | 'paypal'; transactionId: string; settledAt: string };

// Bad: when status is 'idle', should gateway/transactionId exist? The type doesn't say.type PaymentState = {  status: 'idle' | 'processing' | 'settled';  gateway?: 'stripe' | 'paypal';  transactionId?: string;  initiatedAt?: string;  settledAt?: string;};
// Good: each status carries exactly the fields it needs.type PaymentState =  | { status: 'idle' }  | { status: 'processing'; gateway: 'stripe' | 'paypal'; transactionId: string; initiatedAt: string }  | { status: 'settled'; gateway: 'stripe' | 'paypal'; transactionId: string; settledAt: string };

Null over sentinels

// Bad: 'none' is not an action. It is the absence of one.type PendingAction = 'none' | 'confirm-address' | 'select-shipping';
// Goodtype PendingAction = 'confirm-address' | 'select-shipping';type OrderState = { pendingAction: PendingAction | null };

// Bad: 'none' is not an action. It is the absence of one.type PendingAction = 'none' | 'confirm-address' | 'select-shipping';
// Goodtype PendingAction = 'confirm-address' | 'select-shipping';type OrderState = { pendingAction: PendingAction | null };

Phased composition over grab-bags

// Bad: 20+ optional fields. Every consumer does profile.firstName ?? defaults.firstName.type UserProfile = {  firstName?: string;  lastName?: string;  email?: string;  phone?: string;  company?: string;  jobTitle?: string;  billingAddress?: string;  cardLast4?: string;  // ... more};
// Good: check one optional instead of eight. When identity exists, all its fields are present.type UserProfile = {  identity?: { firstName: string; lastName: string; email: string };  billing?: { address: string; cardLast4: string };};

// Bad: 20+ optional fields. Every consumer does profile.firstName ?? defaults.firstName.type UserProfile = {  firstName?: string;  lastName?: string;  email?: string;  phone?: string;  company?: string;  jobTitle?: string;  billingAddress?: string;  cardLast4?: string;  // ... more};
// Good: check one optional instead of eight. When identity exists, all its fields are present.type UserProfile = {  identity?: { firstName: string; lastName: string; email: string };  billing?: { address: string; cardLast4: string };};

Brand identical primitives

// Bad: a function accepting UserId will happily take a TeamId.type UserId = string;type TeamId = string;
// Goodtype UserId = string & { readonly __brand: 'user' };type TeamId = string & { readonly __brand: 'team' };

// Bad: a function accepting UserId will happily take a TeamId.type UserId = string;type TeamId = string;
// Goodtype UserId = string & { readonly __brand: 'user' };type TeamId = string & { readonly __brand: 'team' };

Delete dead variants

If a type has a variant that is never constructed, delete it. A status: 'open' | 'completed' where 'completed' is never set suggests a lifecycle that does not exist.

3. Enforce function contracts

Never add side effects to a pure function

When a pure function quietly gains a side effect, every callsite inherits behavior it did not ask for. If a function needs side effects, extract them into a separate orchestrator.

Semantic functions are small, pure, and self-describing. All inputs in, all outputs out, no hidden effects.
Pragmatic functions are orchestrators. They compose semantic functions and contain messy domain glue.

Before: semantic function that grew into a pragmatic one

function handleWebhook(state, eventType, payload, receivedAt): WebhookResult {  switch (eventType) {    case 'payment.captured': {      const receipt = buildReceipt(payload);            // data creation      state.order.paymentStatus = 'captured';           // mutation      state.order.receipt = receipt;                     // mutation      state.user.lastPurchaseAt = receivedAt;           // mutation      state.user.lifetimeSpend += receipt.amount;        // mutation      clearPendingAction(state);                         // side effect      const notifications = buildPaymentNotifs(state);   // notification      state.notifications.push(...notifications);        // mutation      recalculateDashboard(state);                       // derivation      return { state, output: receipt, notifications };    }    // ... 12 more cases, same pattern  }}

function handleWebhook(state, eventType, payload, receivedAt): WebhookResult {  switch (eventType) {    case 'payment.captured': {      const receipt = buildReceipt(payload);            // data creation      state.order.paymentStatus = 'captured';           // mutation      state.order.receipt = receipt;                     // mutation      state.user.lastPurchaseAt = receivedAt;           // mutation      state.user.lifetimeSpend += receipt.amount;        // mutation      clearPendingAction(state);                         // side effect      const notifications = buildPaymentNotifs(state);   // notification      state.notifications.push(...notifications);        // mutation      recalculateDashboard(state);                       // derivation      return { state, output: receipt, notifications };    }    // ... 12 more cases, same pattern  }}

After: composed from semantic functions

function handlePaymentCaptured(state: AppState, payload: PaymentPayload, receivedAt: string): WebhookResult {  const receipt = buildReceipt(payload);  const updatedOrder = applyPaymentToOrder(state.order, receipt);  const updatedUser = applyPurchaseToUser(state.user, receipt, receivedAt);  const notifications = buildPaymentNotifs(state, receipt);
  return {    state: { ...state, order: updatedOrder, user: updatedUser },    output: receipt,    notifications,  };}

function handlePaymentCaptured(state: AppState, payload: PaymentPayload, receivedAt: string): WebhookResult {  const receipt = buildReceipt(payload);  const updatedOrder = applyPaymentToOrder(state.order, receipt);  const updatedUser = applyPurchaseToUser(state.user, receipt, receivedAt);  const notifications = buildPaymentNotifs(state, receipt);
  return {    state: { ...state, order: updatedOrder, user: updatedUser },    output: receipt,    notifications,  };}

Pick a mutation contract

If a function mutates its input, return void. If it returns a value, clone first. Never mutate the input and return the same reference — callers cannot tell whether to use the return value or the original.

// Bad: mutates AND returns the same objectfunction withPendingAction(state: AppState, action: string): AppState {  state.pendingAction = action;  return state;}
// Good: mutate, return voidfunction applyPendingAction(state: AppState, action: string): void {  state.pendingAction = action;}
// Also good: clone, return newfunction withPendingAction(state: AppState, action: string): AppState {  return { ...state, pendingAction: action };}

// Bad: mutates AND returns the same objectfunction withPendingAction(state: AppState, action: string): AppState {  state.pendingAction = action;  return state;}
// Good: mutate, return voidfunction applyPendingAction(state: AppState, action: string): void {  state.pendingAction = action;}
// Also good: clone, return newfunction withPendingAction(state: AppState, action: string): AppState {  return { ...state, pendingAction: action };}

4. Data over procedure

When a long if-chain returns a similar shape from every branch, the logic is a lookup table encoded as code. Convert it to data.

Before: if-chain

function getStepInfo(step: string): StepInfo | null {  if (step === 'verify-email') {    return { tone: 'action', title: 'Verify your email', detail: 'Check your inbox' };  }  if (step === 'add-payment') {    return { tone: 'action', title: 'Add payment method', detail: 'Enter card details' };  }  if (step === 'review-order') {    return { tone: 'confirm', title: 'Review your order', detail: 'Check totals' };  }  // ... 10 more branches  return null;}

function getStepInfo(step: string): StepInfo | null {  if (step === 'verify-email') {    return { tone: 'action', title: 'Verify your email', detail: 'Check your inbox' };  }  if (step === 'add-payment') {    return { tone: 'action', title: 'Add payment method', detail: 'Enter card details' };  }  if (step === 'review-order') {    return { tone: 'confirm', title: 'Review your order', detail: 'Check totals' };  }  // ... 10 more branches  return null;}

After: declarative table

const STEP_INFO: Array<{  match: (step: string) => boolean;  info: StepInfo;}> = [  { match: (s) => s === 'verify-email', info: { tone: 'action', title: 'Verify your email', detail: 'Check your inbox' } },  { match: (s) => s === 'add-payment',  info: { tone: 'action', title: 'Add payment method', detail: 'Enter card details' } },  { match: (s) => s === 'review-order', info: { tone: 'confirm', title: 'Review your order', detail: 'Check totals' } },  // data, not code];
function getStepInfo(step: string): StepInfo | null {  return STEP_INFO.find(({ match }) => match(step))?.info ?? null;}

const STEP_INFO: Array<{  match: (step: string) => boolean;  info: StepInfo;}> = [  { match: (s) => s === 'verify-email', info: { tone: 'action', title: 'Verify your email', detail: 'Check your inbox' } },  { match: (s) => s === 'add-payment',  info: { tone: 'action', title: 'Add payment method', detail: 'Enter card details' } },  { match: (s) => s === 'review-order', info: { tone: 'confirm', title: 'Review your order', detail: 'Check totals' } },  // data, not code];
function getStepInfo(step: string): StepInfo | null {  return STEP_INFO.find(({ match }) => match(step))?.info ?? null;}

Easier to scan, extend, and test. An agent adding a new step adds a data entry, not a branch in a control flow.

When NOT to convert

If branches have different control flow — not just different return values — keep them as code. A table maps inputs to outputs; it cannot express "call X then conditionally call Y."

Checklist

When reviewing code (yours or an agent's):

Can any new field be derived from existing state? Derive it.
Is mutable state visible beyond its minimal scope? Trap it in a closure.
Do any models allow field combinations that should be impossible? Discriminated union.
Are there sentinel values ('none', 'unknown', -1) where null would work? Use null.
Are there identical type aliases for different domain concepts? Brand or eliminate.
Does any function both mutate its input and return it? Pick one contract.
Has a semantic function grown side effects? Extract them.
Is there an if-chain where every branch returns a similar shape? Make it a table.
Are there dead type variants never constructed? Delete them.

Source and attribution

Source:gbasin/clanker-disciplineat commit6d933da

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Clanker Discipline

Clanker Discipline

1. Derive, don't store

Before: cached flags

After: derive from evidence

When NOT to derive

If you cannot derive, encapsulate

The debugging payoff

2. Make wrong states impossible

Discriminated unions over optional bags

Null over sentinels

Phased composition over grab-bags

Brand identical primitives

Delete dead variants

3. Enforce function contracts

Never add side effects to a pure function

Before: semantic function that grew into a pragmatic one

After: composed from semantic functions

Pick a mutation contract

4. Data over procedure

Before: if-chain

After: declarative table

When NOT to convert

Checklist

Source and attribution

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices