teach

name	teach
description	This skill should be used when the user asks to "explain this violation", "teach me about clean code", "why is this bad", "what's wrong with long functions", "explain single responsibility", "what does DRY mean", "teach me about interfaces", "explain this principle", "why do we need interfaces", "what is OOP", or when the user wants to understand the reasoning behind a clean code rule. Provides a clear explanation with a book citation, counter-example, and how to fix it.
argument-hint	[violation-type: file-too-long | function-too-long | too-many-parameters | deep-nesting | bad-naming | missing-interface | dry-violation | comments | human-readability]
allowed-tools	Read
version	0.1.0

Clean Code Teach

Explain a clean code principle clearly — why it matters, what the rule is, where it comes from, and how to apply it. Always include a book citation, a counter-example showing the problem, and a clean version showing the solution.

Structure of Every Teaching Response

Always follow this format:

## [Principle Name]

**The rule:** [One-sentence rule]

**Why it matters:**
[2-3 sentences on real impact — bugs, maintenance cost, onboarding time]

**Book reference:**
[Title, Chapter/Page] — [Short quote]

**The problem (before):**
[Code example showing the violation]

**The fix (after):**
[Code example showing the clean version]

**Remember:** [One memorable takeaway]

Mapping Arguments to Principles

When $ARGUMENTS is provided, map to the corresponding principle:

Argument	Principle
file-too-long, monolith, long-file	Single Responsibility — file level
function-too-long, long-function	Do One Thing
too-many-parameters, parameters, params	Parameter Objects
deep-nesting, nesting	Guard Clauses
bad-naming, naming, names	Intention-Revealing Names
missing-interface, interface, interfaces	Dependency Inversion
dry-violation, dry, duplication	DRY
comments, commenting	Self-Documenting Code
human-readability, readability, readable	Optimize for the Reader
solid	All SOLID principles overview
oop	OOP principles overview
srp	Single Responsibility Principle
open-closed, ocp	Open/Closed Principle
liskov, lsp	Liskov Substitution Principle
interface-segregation, isp	Interface Segregation Principle
dependency-inversion, dip	Dependency Inversion Principle

When No Argument Is Provided

If $ARGUMENTS is empty, ask the user which principle they want to learn about. Present the list:

Which clean code principle would you like to learn about?

1. **file-too-long** — Why monolith files are dangerous
2. **function-too-long** — Why functions must do one thing
3. **too-many-parameters** — Why parameter count matters
4. **deep-nesting** — How guard clauses simplify code
5. **bad-naming** — Why names are the most important documentation
6. **missing-interface** — Why TypeScript interfaces matter
7. **dry-violation** — The cost of duplicated logic
8. **comments** — When to comment and when not to
9. **human-readability** — The ultimate test for clean code
10. **solid** — All 5 SOLID principles

Or ask any question: "why do functions need to be short?"

Context-Aware Teaching

When teaching, adapt the examples to the user's language:

• Detect the project language from recent files or conversation context
• Show TypeScript examples for TS projects, Python for Python, Java for Java
• If the user showed you a specific piece of code, use that as the "before" example

Connecting Principles to the Books

Always cite from one of the three source books:

• "The Art of Clean Code" (Mayer) — focuses on practical day-to-day clean code habits
• "Code Complete 2nd Ed." (McConnell) — focuses on the craft and quantitative research
• "OOP vs. Functional Programming" — focuses on design patterns and paradigm choices

Use exact chapter references when available. See references/principles.md for all citations.

Teaching SOLID (Overview)

When asked about SOLID as a whole:

## SOLID Principles

**S — Single Responsibility**
A class has one reason to change. If you need "and" to describe it, split it.

**O — Open/Closed**  
Open for extension, closed for modification. Add behavior through new classes, not by editing existing ones.

**L — Liskov Substitution**
Subtypes must be substitutable for their base types without breaking correctness.

**I — Interface Segregation**
Don't force clients to depend on methods they don't use. Keep interfaces small and focused.

**D — Dependency Inversion**
Depend on abstractions (interfaces), not concretions (classes). High-level modules don't import low-level ones.

Ask /cleancode:teach [s|o|l|i|d] for a deep dive into any principle.

Additional Resources

Reference Files

• references/principles.md — Full principle explanations with detailed book citations, counter-examples in multiple languages, and fix strategies for every violation type. Read this to get the full teaching content for any principle.