home / skills / ahonn / dotfiles / code-quality

code-quality skill

safe

This skill enforces code-quality standards by promoting readability, modular design, and proactive smells detection during writing and review.

npx playbooks add skill ahonn/dotfiles --skill code-quality

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.0 KB

---
name: code-quality
description: "Code quality standards. Defines complexity management, modular design, code smell detection. Applied automatically when writing or reviewing code."
user-invocable: false
---

# Programming Philosophy and Quality Standards

## Core Philosophy

- Code is primarily written for humans to read and maintain; machine execution is a by-product
- Priority: **Readability & Maintainability > Correctness > Performance > Code length**
- Follow idiomatic practices of each language community

## Complexity Management

```
Complexity = Dependencies + Obscurity
```

### Symptoms to Watch For

| Symptom | Description |
|---------|-------------|
| **Change Amplification** | Small changes require modifications in many places |
| **Cognitive Load** | Developers need excessive information to complete tasks |
| **Unknown Unknowns** | Unclear what code needs modification (worst symptom) |

### Mitigation Strategies

- "Zero tolerance" for incremental complexity growth
- Invest time upfront in design
- Avoid tactical shortcuts that create technical debt

## Modular Design Principles

- **Deep Modules**: Powerful functionality through simple interfaces
- **Information Hiding**: Encapsulate design decisions within implementations
- **General-Purpose Design**: Combat over-specialization
- **Avoid "Classitis"**: More classes/components ≠ better design

## Code Smells to Watch For

Proactively identify and flag:
- Duplicated logic / copy-paste code
- Over-tight coupling or circular dependencies
- Fragile designs where one change breaks unrelated parts
- Unclear intent, confused abstractions, vague naming
- Over-engineering without real benefit

When identifying code smells:
- Explain the problem concisely
- Provide 1–2 refactoring directions with pros/cons

## Error Handling Strategy

- **Define errors out of existence** — design APIs with no exceptions when possible
- **Mask exceptions** at low levels to protect higher layers
- **Aggregate exceptions** with general-purpose handlers
- **Just crash** for rare, unrecoverable errors

Overview

This skill enforces code quality standards focused on readability, maintainability, and manageable complexity. It codifies principles for modular design, code smell detection, and pragmatic error handling. Applied automatically during code authoring and review, it gives concise guidance and concrete refactoring suggestions.

How this skill works

The skill inspects code for complexity drivers (dependency sprawl and obscurity), modularity violations, and common code smells like duplication and tight coupling. When it detects issues, it explains the problem briefly and proposes 1–2 practical refactor directions with their trade-offs. It also validates error-handling patterns against recommended strategies to reduce accidental runtime surprises.

When to use it

During automated code reviews to flag maintainability regressions early
When adding features to ensure changes don’t amplify complexity
Refactoring sessions to identify fragile or over-engineered areas
Design discussions to evaluate modularity and information hiding
Before releases to catch unclear intent or dangerous coupling

Best practices

Prioritize readability and maintainability over micro-optimizations
Keep modules deep: expose small, stable interfaces with rich internals
Adopt zero-tolerance for incremental complexity growth
Prefer general-purpose abstractions over over-specialized components
When reporting smells, give a concise problem statement and 1–2 refactoring options

Example use cases

Detect duplicated logic across configuration modules and suggest consolidation
Flag change-amplifying dependencies before a new feature is merged
Recommend information-hiding boundaries when internals leak through interfaces
Evaluate error propagation and suggest masking or aggregation where appropriate
Point out vague naming and propose clearer, intent-revealing identifiers

FAQ

How prescriptive are the refactoring suggestions?

Suggestions are pragmatic: each issue includes one or two concrete options with pros and cons so you can choose based on context.

Will this prioritize performance issues?

Performance is considered but ranked below readability and maintainability; the skill flags performance only when it conflicts with core quality goals.