Clean Code Agent Skill

Clean Code

Config Resolution

Skill support project custom. Order:

• Look .lattice/config.yaml in repo root
• If found, check paths.clean_code for custom doc path
• If custom path exist, read doc and check YAML frontmatter for mode:
• mode: override (or no mode): Custom doc full precedence. Use instead embedded default. Must be comprehensive -- sole reference.
• mode: overlay: Read embedded ./references/defaults.md first, then apply custom doc sections on top. Custom sections replace matching sections in default (matched by heading). New sections appended after default.
• If no config/path/file, read ./references/defaults.md
• Language adaptation: If paths.language_idioms exist in config, read that document and adapt defaults using these sections:
• "Error Handling" → adapt §8 (Error Handling) patterns to language idioms. Language idioms take precedence over pseudocode defaults.
• "Type System & Object Model" → adapt §1 (Single Responsibility) cohesion guidance to language constructs (e.g., struct vs class).
• "Naming Conventions" → adapt §4 (Meaningful Naming) patterns to language conventions.
• "Parameter & Function Design" → adapt §2 (Small, Focused Functions) and §5 (Parameter Design) to language capabilities.
• "Dependency Management" → adapt §9 (Test-Friendly Code) DI patterns to language idioms.

Self-Validation Checklist

STOP after each component. Verify ALL. Fix any failed check before presenting. Judgment calls → flag with options (see Ambiguity Signals).

• SINGLE RESPONSIBILITY: Describe each function without "and"? If not → extract separate function.
• SIZE: Each function under size threshold per loaded doc (~20 lines default)? If not → extract sub-operation into named function.
• COMPLEXITY: Cyclomatic complexity under threshold per loaded doc (~10 default)? If not → flatten with guard clause, extract branch.
• ABSTRACTION LEVEL: Each function operate at one level? If high-level mixed with low-level → extract detail.
• NAMING: Function/variable name reveal intent without context? If not → rename self-documenting.
• PARAMETERS: Parameter count under threshold per loaded doc (4 default)? If not → group into object.
• PRIMITIVE OBSESSION: String/number/boolean clearer as named type? If so → introduce parameter object or typed wrapper.
• ERROR HANDLING: Every fail-able operation have explicit handling with actionable message? Handled at right level?

Project-specific checks: If loaded doc (from Config Resolution) contains a Validation Checklist section (§10), apply those checks as additional project-specific validation after the checklist above.

Active Anti-Pattern Scan

After checklist, scan for these. If find, fix before present.

• [ ] God Function: Function exceed ~30 lines doing multiple thing; description need "and" → extract focused function
• [ ] Deep Nesting: Three+ level indentation → flatten with early return/guard clause
• [ ] Cryptic Naming: Variable like d, tmp2, processData → rename reveal intent
• [ ] Long Parameter Lists: Five+ parameter → group into object or split function
• [ ] Premature Abstraction: Utility extracted from only two similar block → inline until Rule of Three with same reason to change
• [ ] Swallowed Errors: Empty catch, generic "something went wrong," silently return null → handle explicitly
• [ ] Comments as Deodorant: Comment explain convoluted code instead refactor → rename self-documenting; keep only "why" comment, remove "what"
• [ ] Hidden Side Effects: Function named getX also write cache/send notification → rename or separate
• [ ] Dead Code: Commented-out block, unused import, unreachable branch → delete (version control preserve)
• [ ] Untestable Logic: Side effect tangled with business logic; unit test need mock I/O → push side effect to boundary, extract pure function, inject dependency

Ambiguity Signals

Multiple valid outcome. Present option rather than silently choose. See ./references/defaults.md for resolution guidance on each signal below.

• Single Responsibility: Two tightly-coupled sequential operation may be one responsibility (pipeline), not two. "And" test catch true violation AND false positive.
• Function Size: Near-threshold (20-30 lines) with one clear purpose -- extract may create five unclear smaller function. Present tradeoff.
• DRY vs Premature Abstraction: Two identical block may serve different purpose and diverge. Until third instance with same reason to change, genuinely ambiguous.
• Error Handling Strategy: Exception vs Result type vs error code depend on language idiom and team convention, not universal.