back
loading skill details...
Catches state bloat, grab-bag models, and mutation ambiguity from AI coding agents. Use when reviewing state types, boolean flags, optional-field models, or…
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;
}
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';
}
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 class
class 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 closure
function 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);
});
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 };
Null over sentinels
// Bad: 'none' is not an action. It is the absence of one.
type PendingAction = 'none' | 'confirm-address' | 'select-shipping';
// Good
type 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 };
};
Brand identical primitives
// Bad: a function accepting UserId will happily take a TeamId.
type UserId = string;
type TeamId = string;
// Good
type 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
}
}
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,
};
}
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 object
function withPendingAction(state: AppState, action: string): AppState {
state.pendingAction = action;
return state;
}
// Good: mutate, return void
function applyPendingAction(state: AppState, action: string): void {
state.pendingAction = action;
}
// Also good: clone, return new
function 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;
}
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;
}
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.
26:["$don't have the plugin yet? install it then click "run inline in claude" again.
structured original content into implexa's 6 components, added explicit decision points with exception cases, clarified inputs and external connections, added edge cases and testing guidance, and separated semantic from pragmatic orchestration into procedure steps.
apply disciplined rules when writing or reviewing state types, data models, and functions that manage application state. ai coding agents tend to add flags, optional fields, and special cases that compound into unmaintainable state. use this skill when you encounter state creep, boolean proliferation, optional-field models, ambiguous mutation contracts, or if-chains that encode lookup tables as control flow. the goal is clean, maintainable code that makes wrong states impossible and derives facts from evidence rather than storing them.
scan for stored derivations: walk through all boolean fields, optional fields, and cached computed values in the state type or model. for each one, ask "can this be computed from data that already exists?" if yes, mark it for removal and plan the derivation function.
identify the evidence source: determine what event stream, data source, or existing fields you can derive from. prefer event logs (immutable records of what happened) over reconstructing from scattered state. document the derivation logic in a pure function.
replace stored values with derivation: delete the boolean or optional field from the state type. write a pure function that takes the evidence (events, existing fields, or both) and returns the answer. add a test that feeds fixture data and verifies the output.
audit mutable state scope: scan for fields that are mutated in multiple places or visible across class methods. if mutable state exists and cannot be derived, trap it in the smallest scope (prefer closures over class fields). verify that no code path outside the closure can touch it.
convert grab-bag models to discriminated unions: find types with many optional fields (especially when some fields should only exist together). redesign as a discriminated union (tagged types) so that each variant carries exactly the fields it needs and no others.
replace sentinels with null: look for magic strings or numbers like 'none', 'unknown', -1, or 'unset' that represent the absence of a value. replace them with null or undefined, which are explicit and type-checkable.
brand identical primitives: find type aliases for string or number that represent different domain concepts (e.g., UserId and TeamId both aliased to string). add a brand property to distinguish them at the type level.
delete dead variants: scan for enum variants or union branches that are never constructed in the codebase. delete them; they are noise and a source of bugs.
enforce function contracts: review functions that touch state. if a function is pure (no side effects), verify it does not mutate its input or call external services. if it needs side effects, extract them into a separate orchestrator function.
separate semantic from pragmatic functions: pure, self-describing functions should do one thing and express it in their signature. if a function has grown side effects or orchestrates multiple state mutations, split it: keep the semantic logic pure and move orchestration to a separate pragmatic function.
pick a mutation contract: if a function mutates its input, return void. if it returns a value, clone first. never both mutate the input and return the same reference.
convert if-chains to data tables: when an if-chain (or switch statement) has branches that return the same shape (same fields, different values), convert it to a declarative data table (array of objects or map). this makes the logic scannable and easier for agents to extend without modifying control flow.
if a value can be derived from existing state or an event stream, do not store it. the exception is when the derivation would be significantly more complex than storing the value, or when the value contains temporal or external data (timestamps, API responses) that cannot be rederived.
if mutable state must exist, encapsulate it in the smallest scope (closure or local variable) rather than exposing it as a class field or object property. the exception is when the domain genuinely has a state machine with ordered transitions (e.g., a checkout step is not a cached conclusion; it IS the state).
if a model has many optional fields, convert to a discriminated union so each variant carries exactly the fields it needs. the exception is when the fields are genuinely independent (e.g., a configuration object where any subset of settings may be present).
if a function both mutates its input and returns a value, pick one contract: mutate and return void, or clone and return the new value. never do both, because callers cannot tell whether to use the original or the return value.
if a semantic function has grown side effects (mutations, logging, API calls, notifications), extract the side effects into a separate pragmatic orchestrator function. the exception is when the side effect is so tightly bound to the semantic logic that separating them would obscure intent.
if an if-chain or switch statement returns a similar shape from every branch, convert it to a data table. the exception is when branches have different control flow (e.g., one branch calls function X then conditionally calls Y), in which case keep them as code.
refactored state types: type definitions that use discriminated unions, null instead of sentinels, and branded primitives where applicable. no optional fields that should be impossible combinations. dead variants removed.
pure derivation functions: functions that take evidence (events, state slices, or both) and return computed values. must have zero side effects, clear parameter names, and test coverage showing fixture data in and answer out.
encapsulated mutable state: if state must be mutable, it lives in a closure or private scope with documented entry points. no code path outside that scope can touch it.
separated semantic and pragmatic functions: semantic functions are small, pure, and self-describing. pragmatic functions orchestrate them. each has a clear contract in its signature.
data tables: declarative arrays or maps that replace if-chains. must be easy to scan and extend without modifying control flow.
test fixtures: unit tests that feed known event sequences or state snapshots and verify the output. tests are data-in, answer-out with no mocking or timing reproduction needed.
the code is reviewed or refactored and passes all existing tests plus new tests that exercise edge cases (empty event streams, missing optional fields, dead code paths).
boolean and optional fields that were stored are now gone; their answers come from pure functions that read evidence.
mutable state is trapped in closures or localized scopes. code outside those scopes cannot touch it.
types no longer allow invalid field combinations. a discriminated union or branded types prevent type mismatches.
if-chains have been converted to data tables. the logic is scannable and extends via data entry, not code branching.
mutation contracts are explicit: functions either mutate and return void, or clone and return a new value. no function does both.
semantic functions are pure and side-effect free. pragmatic orchestrators handle the messy domain glue.
diffs are bigger now but the codebase is cleaner: fewer moving parts, fewer mutation sites, fewer state combinations that can go wrong.