Override generic LLM code output patterns. Replaces generic variable names, over-commented code, and placeholder patterns with domain-specific naming, clean architecture, and production-ready structure.
context
fork
Code output uplift
LLMs produce code with predictable failure modes: generic variable names (data, result, response), comments that restate what the code does rather than why, untyped parameters disguised behind any, and American English in user-facing strings. This skill replaces those defaults with domain-specific naming, intentional commenting, strict typing, and en-AU compliance.
The skill is rigid. Every piece of code produced under its governance must pass the eval criteria at the end of this file. There are no soft recommendations here — each rule exists because its violation is detectable and its correction is measurable.
When to apply
Positive triggers
Activate this skill when the task involves improving or reviewing code quality:
Any task where the primary goal is improving existing code structure, naming, or readability
Negative triggers
Do not activate for tasks where a different skill is the primary driver:
Task initiation or feature creation (use idea-to-production or genesis-orchestrator)
UI design, animation, or visual styling (use scientific-luxury)
Algorithm optimisation or complexity analysis (use council-of-logic)
Document formatting or technical writing (use document-formatting-uplift)
Test-driven development workflow (use tdd)
Priority
This skill activates after council-of-logic (which governs algorithmic decisions) and before execution-guardian (which governs safety checks). The council determines the right algorithm; this skill determines how that algorithm is expressed in code.
Banned defaults
Twelve anti-patterns that LLMs produce by default. Each is banned unconditionally.
Disables the type system at the boundary where it matters most; errors surface at runtime instead of compile time
unknown with a type guard, or a specific interface/type definition
5
American English in user-facing strings
Violates the project's en-AU locale requirement
Australian English: "colour", "behaviour", "optimisation", "organisation", "licence" (noun)
6
Placeholder TODOs without context: // TODO: fix this
Provides no information about what needs fixing, who should fix it, or when
Contextual TODOs: // TODO(auth): Replace with OAuth flow — blocked on provider setup (BEAD-142) or remove entirely
7
Dead code left in place: commented-out blocks, unreachable branches
Clutters the file, misleads readers about active behaviour, inflates diffs
Delete it. Version control preserves history.
8
Functions exceeding 50 lines
Signals the function handles multiple responsibilities; harder to test, harder to name, harder to reason about
Extract sub-functions with descriptive names that document the decomposition
9
Deeply nested conditionals (more than 3 levels)
Each nesting level doubles the cognitive load for the reader; the happy path becomes invisible
Early returns, guard clauses, or extracted predicate functions
10
Magic numbers and strings
The reader cannot determine why the value is what it is; changes require hunting through the codebase
Named constants: const MAX_RETRY_ATTEMPTS = 3, const SESSION_TIMEOUT_MS = 1800000
11
Inconsistent naming within a file
Mixing camelCase and snake_case in the same TypeScript file, or PascalCase and camelCase for the same concept
One convention per language: camelCase for TypeScript identifiers, snake_case for Python identifiers
12
Import-all patterns: import * as utils from './utils'
Defeats tree-shaking, obscures which specific utilities are used, makes refactoring dangerous
Named imports: import { formatCurrency, parseDate } from './utils'
Reference: See references/anti-patterns.md for full before/after examples of each pattern.
Replacement standards
These rules govern all code output when this skill is active.
Domain-specific naming
Every variable, function, and type name must describe what it represents in the problem domain, not what it is in the programming language. A function that fetches a user's profile from the database is fetchUserProfile, not getData. A variable holding the result of an agent execution is agentExecutionResult, not result. A list of unprocessed nutrition entries is pendingNutritionEntries, not items.
The naming test is simple: could a developer unfamiliar with the codebase understand what the variable holds without reading its assignment? If not, the name is too generic.
Comments for WHY, not WHAT
A comment that restates the code is worse than no comment — it adds reading time while contributing nothing. Comments exist to explain intent, constraints, and non-obvious decisions. "Increment counter" above i++ fails this test. "Skip index 0 — the CSV header row is not a data record" passes because it explains a decision that the code alone does not convey.
When a block of code needs a WHAT comment to be readable, the code itself needs to be rewritten with better names and structure until the WHAT is self-evident.
Zero any without justification
TypeScript's any type is a trapdoor that silently disables type checking across call boundaries. Every any in a function signature, variable declaration, or type assertion must be replaced with either:
A specific type or interface that describes the shape
unknown paired with a type guard that narrows the type at the usage site
A justified exception documented with a comment explaining why the type cannot be expressed (rare — typically only at FFI boundaries or with genuinely polymorphic third-party libraries)
en-AU enforcement
All user-facing strings, comments, error messages, and documentation within code must use Australian English spelling. This applies to variable names only when they appear in user-visible contexts (log messages, error strings, UI text). Internal variable names follow domain conventions regardless of spelling variant.
Functions under 50 lines
A function that exceeds 50 lines is handling multiple responsibilities. Extract coherent sub-operations into named functions. The extracted function's name serves as documentation for what that block of code does — a form of self-documenting code that is more maintainable than comments.
Early returns over nesting
Replace nested conditionals with guard clauses that exit early for invalid or edge-case conditions. The main logic should run at the lowest indentation level, making the happy path immediately visible. A function with three levels of if nesting should be refactored to handle error conditions first and then proceed with the core logic at the top level.
Named constants
Every literal value that is not self-evidently obvious (0, 1, true, false, empty string) must be a named constant. The constant's name documents the value's purpose: const AGENT_TIMEOUT_MS = 30000 communicates both the value and its meaning. 30000 alone communicates nothing.
Consistent conventions
TypeScript files use camelCase for variables, functions, and methods; PascalCase for types, interfaces, and React components; SCREAMING_SNAKE_CASE for constants. Python files use snake_case for variables, functions, and methods; PascalCase for classes; SCREAMING_SNAKE_CASE for constants. Never mix conventions within a file.
Naming conventions
Context
Convention
Example
React components
PascalCase.tsx
AgentDashboard.tsx, NutritionChart.tsx
React hooks
use{Domain}{Action}
useAgentStatus, useNutritionEntries
TypeScript utilities
kebab-case.ts
format-currency.ts, parse-agent-response.ts
Python modules
snake_case.py
agent_executor.py, nutrition_service.py
Python functions
snake_case
calculate_nutrient_totals, fetch_agent_state
Test files (TS)
{Component}.test.tsx
AgentDashboard.test.tsx
Test files (Python)
test_{module}.py
test_agent_executor.py
Variables (TS)
Domain-specific camelCase
agentExecutionResult, pendingNutritionEntries
Variables (Python)
Domain-specific snake_case
agent_execution_result, pending_nutrition_entries
Constants (both)
SCREAMING_SNAKE_CASE
MAX_RETRY_ATTEMPTS, SESSION_TIMEOUT_MS
Types/Interfaces
PascalCase
AgentExecutionResult, NutritionEntry
API route handlers
verb + Resource
createAgent, get_nutrition_entries
Domain prefixes in this project
Variables and functions should use domain prefixes drawn from the project's bounded contexts:
agent_ / agent — AI agent execution, state, coordination
auth_ / auth — Authentication and authorisation flows
Spelling: colour, behaviour, optimisation, organised, licence (noun), analyse, centre, defence, honour, programme (but "program" for software variables).
Internal identifiers follow the language ecosystem's conventions (American English is acceptable for variable names that mirror library APIs, e.g., color in CSS-in-JS contexts where the library uses American spelling).
Eval criteria
Every code file produced under this skill must pass all eight checks. A single failure means the code requires revision.
#
Criterion
PASS condition
1
Domain-specific naming
Zero instances of data, result, response, item, temp, val, obj, arr as standalone variable names. Every name describes what it represents in the domain.
2
Comments for WHY
No comments that restate what the code does. Every comment explains intent, constraints, or non-obvious decisions.
3
No unstructured logging
Zero console.log statements in production code. All logging uses structured logger with context objects.
4
Type safety
Zero any types without an inline justification comment. All function parameters and return types are explicitly typed.
5
en-AU compliance
All user-facing strings, error messages, and comments use Australian English spelling.
6
Function size
No function exceeds 50 lines. Functions with multiple responsibilities are decomposed.
7
Nesting depth
No conditional nesting deeper than 3 levels. Guard clauses and early returns used for edge cases.
8
Named constants
No magic numbers or strings. All non-obvious literal values are named constants with descriptive names.
Run this checklist mentally before declaring any code task complete. If any criterion fails, fix it before delivering.
