# Clean Code Mentor

> Skill for technical mentorship and code review with total focus on SOLID, YAGNI, DRY, and KISS. Identifies design violations and suggests refactorings for simpler and more maintainable code.

- Skill: `klebersoncollab/clean-code-mentor` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add klebersoncollab/clean-code-mentor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/klebersoncollab/clean-code-mentor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: KlebersonCollab (https://skillmd.com/u/klebersoncollab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/klebersoncollab/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](references/solid-principles.md)** — Technical depth on the 5 principles with examples.
2. **[YAGNI & KISS](references/yagni-and-kiss.md)** — The power of simplicity and delivery based on current needs.
3. **[DRY & Clean Tests](references/dry-and-clean-tests.md)** — Eliminating duplication and maintaining test quality.

---

## Output Structure

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

| Artifact | Format | Description |
|----------|---------|-----------|
| **Review Report** | `.md` | Structured audit report with severity (Critical, Warning, Info). |
| **Refactoring Diff** | Markdown/Diff | Before vs. After comparison with the suggested logic. |
| **Mentoring Summary** | `.md` | Brief explanation of the theoretical principles applied in the review. |


---

<!-- @sdd-state -->
```yaml
version: "2.3.0"
feature_id: "HUB-ALIGNMENT"
phase: "VERIFY"
status: "COMPLETED"
last_update: "2026-05-06T13:16:19.380072Z"
evidence_checksum: "8e52f6a"
```