Clean Code Mentor

🔒 Prerequisites (Mandatory)

This skill operates WITHIN the SDD framework. Before starting any technical execution: 0. Mode Check: Verify the current operational mode (.hub-mode) and apply the token-distiller skill guidelines.

1. Context Check: Did you rehydrate the context by reading .specs/project/STATE.md, .specs/project/MEMORY.md, and .specs/project/LEARNINGS.md?
2. Spec Check: Does the spec.md file exist with clear requirements and Acceptance Criteria (ACs)? (BDD mandatory for Medium+).
3. Plan Check: Does the plan.md file define the architecture and schemas, and include Mermaid diagrams?
4. Contract Check: Was the contract.md file established with validation sensors?
5. Task Check: Is the task list in .specs/project/tasks.md (or feature-specific) detailed and atomized?

Clean Code Mentor

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." — Martin Fowler

Goal

Empower the agent to act as an experienced code reviewer and technical mentor, auditing software design against SOLID, YAGNI, DRY, and KISS principles, ensuring that simplicity and maintainability are the highest priority in every code delivery.

Workflow (4 Phases)

Phase 1: CONTEXT — Scope Understanding

1. Map Intent: Understand what the current code is trying to achieve before criticizing the design.
2. Map Dependencies: Identify relationships between classes and modules that may indicate violations of SRP (Single Responsibility Principle) or DIP (Dependency Inversion Principle).

Phase 2: AUDIT — Principles Verification

1. SOLID Scan: Evaluate each of the 5 principles. Flag classes that do "too much" or inheritances that break the contract (LSP).
2. YAGNI & KISS Guard: Look for unnecessary abstractions, complex design patterns applied to simple problems, and "placeholder code" for the future.
3. DRY Verification: Check for logic duplication within the file or across related files.

Phase 3: PROPOSE — Refactoring Suggestions

1. Improvement Draft: Propose comparative code snippets (Before vs. After) that apply the suggested improvements.
2. Minimum Impact: Ensure the proposed refactoring does not change the functional behavior of the code (only the structure).

Phase 4: MENTOR — Technical Rationale

1. Foundational Support: Explain the theory behind the fix (e.g., "This reduces coupling...").
2. Quality Audit:
   • Perform a manual audit against the Hub's CONVENTIONS.md and identified quality standards.
3. Handoff: Deliver a structured "Quality Report" with Severity and Recommendations.

Quality Rules

• Simplicity First: Always prioritize the most readable and direct code (KISS) over the most elegant design pattern.
• Evidence-Based: Every critique must be accompanied by a theoretical explanation and a practical example.
• Actionable: Don't just point out errors; always provide a clear path for correction (refactoring).
• Context-Aware: Understand that sometimes deadlines or technology impose limits, but the design should be the best possible within those constraints.

Prohibited

• NEVER suggest complex design patterns if a simple solution solves the problem.
• NEVER ignore obvious "Code Smells" like giant methods or infinite parameter lists.
• NEVER suggest changes that break the style consistency of the current project.
• NEVER criticize code subjectively; always use established principles as a basis.

Reference Documentation

This skill includes detailed reference documentation:

1. SOLID Principles — Technical depth on the 5 principles with examples.
2. YAGNI & KISS — The power of simplicity and delivery based on current needs.
3. DRY & Clean Tests — Eliminating duplication and maintaining test quality.

Output Structure

The execution of this skill should result in the following standardized artifacts:

version: "2.3.0"
feature_id: "HUB-ALIGNMENT"
phase: "VERIFY"
status: "COMPLETED"
last_update: "2026-05-06T13:16:19.380072Z"
evidence_checksum: "8e52f6a"