esplotter/code-standards

Skill: Code Standards

This skill defines mandatory coding rules for generated or reviewed code. It is the default baseline for clean-code and style compliance checks.

Primary source:

• docs/guidelines/code-standards.md

Scope

Use when

• Reviewing code quality, naming, typing discipline, and maintainability.
• Writing or refactoring TypeScript code in any layer.
• Evaluating whether a change follows project coding rules.

Do NOT use when

• The task is architecture boundary analysis -> use architecture.
• The task is test-suite routing/coverage strategy -> use tests.

Core rules (non-negotiable)

1. No any.
   • Use explicit, specific types.
2. Small, single-responsibility files.
   • One clear purpose per file.
3. File names match exports.
   • Components/classes: UpperCamelCase.
   • Hooks/utilities: camelCase.
4. No default exports.
   • Always use named exports.
5. Prefer named functions over arrow functions when possible.
6. Prefer interface over type for public/shared contracts.
7. Follow configured ESLint and Prettier rules.
8. Avoid comments unless code cannot be self-explanatory.
9. Use descriptive, intent-revealing names.

Enforcement policy

• Treat non-negotiable rule violations as findings requiring explicit fixes.
• Distinguish hard violations from optional readability suggestions.
• Do not request broad rewrites when a minimal compliant patch solves the issue.

Review checklist

For each reviewed file, verify:

1. Typing quality
   • No any, no avoidable weak typing in public contracts.
2. API and export conventions
   • Named exports only, file naming aligned with export identity.
3. Structure and readability
   • Single responsibility, manageable complexity, no accidental duplication.
4. Naming quality
   • Variables/functions/types/files convey behavior and intent.
5. Comment discipline
   • Comments are only present for truly non-obvious context.
6. Tooling compliance
   • Aligns with lint/format standards.

Anti-patterns (blocker)

• Introducing any where concrete typing is possible.
• Default exports in new or modified files.
• Ambiguous naming that obscures behavior.
• Multi-purpose files mixing unrelated responsibilities.
• Adding comments that restate obvious code.

Definition of done

• Mandatory rule violations are fixed or explicitly documented as justified exceptions.
• Suggested improvements are prioritized by maintainability impact.
• Final recommendations are minimal, concrete, and repository-consistent.

Output contract

Return a structured YAML report including:

• status: ok | needs_clarification | error
• summary: one-paragraph code standards assessment
• scope: files/modules and assumptions reviewed
• findings: list of findings with title, severity, evidence, rule, fix
• verdict: ready | ready_with_changes | not_ready
• next_actions: ordered, minimal action plan
• warnings: assumptions, risks, or justified deviations