cleanexpo 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:
- "code quality", "naming conventions", "clean code"
- "code style", "variable naming", "code review"
- "refactor for 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-productionorgenesis-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.
| # | Banned pattern | Why it fails | Replacement |
|---|---|---|---|
| 1 | Generic names: data, result, response, item, temp, val, obj, arr, str, num |
Communicates nothing about the domain; forces the reader to trace the variable's origin to understand its content | Domain-specific names that describe what the value represents: userProfile, agentExecutionResult, authTokenPayload |
| 2 | Comments restating what the code does: // increment counter above i++ |
Doubles the reading time without adding information; the code already says what it does | Comments explaining why: // Skip first element — it's the header row or no comment at all |
| 3 | console.log in production code |
Pollutes stdout, leaks data, provides no structured context for debugging | Structured logging: logger.info('Agent execution completed', { agentId, durationMs, tokenCount }) |
| 4 | any types without justification |
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
unknownpaired 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, coordinationauth_/auth— Authentication and authorisation flowsnutrition_/nutrition— Nutrition tracking domain (if applicable)session_/session— User session managementgraph_/graph— LangGraph state and execution
en-AU enforcement
All code produced under this skill must use Australian English in:
- User-facing strings: error messages, UI text, log messages
- Comments and documentation within code files
- Docstrings and JSDoc annotations
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.