typescript-clean-code

What this skill does

# Clean Code

Principles, practices, and workflows for TypeScript developers.

## Critical: Reference-First Approach

**Always load and consult the reference files before applying any principle or making any recommendation.** The references in this skill contain curated, authoritative knowledge from Robert C. Martin's books, adapted for TypeScript. When this skill is active:

1. **Read references before responding** - For any code quality or professional practice topic, load the relevant `rules.md` and `examples.md` files from `references/` before giving advice or writing code. Do not rely on general knowledge alone.
2. **Reference content overrides internal knowledge** - If your general knowledge conflicts with what the reference files state, follow the reference files. They contain the specific rules, thresholds, and patterns this skill enforces.
3. **Cite specific rules** - When making recommendations, reference the specific rule (e.g., "per `references/functions/rules.md` Rule 1: Keep Functions Small, 2-5 lines ideal") so the user can trace the guidance back to its source.
4. **Use examples from reference files** - Prefer the bad/good code examples in `references/[topic]/examples.md` over generating your own. These examples are curated for TypeScript and demonstrate the exact patterns intended.
5. **Follow workflows step-by-step** - When executing a task (review, refactoring, TDD, etc.), load the corresponding workflow file and follow each step, loading the reference files each step points to.

**Do not skip loading references.** Even if you "know" Clean Code principles, the reference files contain specific TypeScript adaptations, thresholds, checklists, and smell catalogs that your general knowledge may not match exactly.

## Quick Start

1. **For a task**: Check `guidelines.md` → find the right workflow → load it → follow each step (loading referenced files)
2. **For reference**: Load the specific `rules.md` and `examples.md` files relevant to your work → apply them
3. **Follow the workflow**: Step-by-step process for consistent results — always load the files each step references

## Workflows

Step-by-step processes for common tasks:

| Workflow | When to Use |
|----------|-------------|
| `workflows/code-review/workflow.md` | Reviewing code for quality |
| `workflows/pr-review/workflow.md` | Reviewing pull requests |
| `workflows/tdd.md` | Test-driven development cycle |
| `workflows/refactoring/workflow.md` | Safe refactoring with tests |
| `workflows/new-feature.md` | Building new functionality |
| `workflows/bug-fix.md` | Fixing bugs properly |
| `workflows/test-strategy.md` | Planning test coverage |
| `workflows/estimation.md` | Estimating tasks (PERT) |
| `workflows/deadline-negotiation.md` | Handling unrealistic deadlines |

### Step-File Architecture (Code Review, PR Review, Refactoring)

The code review, PR review, and refactoring workflows use a **step-file architecture** for context-safe execution:

- Each workflow has a `workflow.md` entry point that describes steps and loads `steps/step-01-init.md`
- Each step is a separate file in `steps/`, loaded sequentially
- Progress is tracked via `stepsCompleted` array in the output document's YAML frontmatter
- If context is compacted mid-workflow, `step-01-init.md` detects the existing output and `step-01b-continue.md` resumes from the last completed step
- Each step loads specific reference files before analysis and cites rules in findings
- The refactoring workflow includes a loop (steps 4-7) for iterative change-test-commit cycles

## Reference Categories

### Part 1: Code Quality (Clean Code book)

| Category | Files | Purpose |
|----------|-------|---------|
| naming | 3 | Variable, function, class naming |
| functions | 4 | Function design and review |
| classes | 3 | Class/module design |
| comments | 3 | Comment best practices |
| error-handling | 3 | Exception handling |
| unit-tests | 3 | Clean test principles |
| formatting | 3 | Code layout |
| smells | 3 | Code smell catalog (50+) |

### Part 2: Professional Practices (Clean Coder book)

| Category | Files | Purpose |
|----------|-------|---------|
| professionalism | 3 | Professional ethics |
| saying-no | 3 | Declining requests |
| commitment | 3 | Making promises |
| coding-practices | 3 | Daily habits, flow, debugging |
| tdd | 3 | TDD workflow and benefits |
| practicing | 3 | Deliberate practice |
| acceptance-testing | 3 | Requirements as tests |
| testing-strategies | 3 | Test pyramid |
| time-management | 3 | Meetings, focus |
| estimation | 3 | PERT estimation |
| pressure | 3 | Working under pressure |
| collaboration | 3 | Working with teams |

## Key Principles (Summary Only — Always Load Full References)

These are abbreviated reminders. **Always load the corresponding reference files for the full rules, thresholds, and examples before applying.**

### Code Quality
1. **Readability** → `references/formatting/rules.md`, `references/naming/rules.md`
2. **Single Responsibility** → `references/classes/rules.md`, `references/functions/rules.md`
3. **Small Units** → `references/functions/rules.md` (Rule 1: 2-5 lines ideal)
4. **Meaningful Names** → `references/naming/rules.md`
5. **DRY** → `references/smells/rules.md` (G5)
6. **Clean Tests** → `references/unit-tests/rules.md`

### Professional Practices
1. **Take Responsibility** → `references/professionalism/rules.md`
2. **Say No** → `references/saying-no/rules.md`
3. **Commit Clearly** → `references/commitment/rules.md`
4. **Estimates != Commitments** → `references/estimation/rules.md`
5. **Stay Clean Under Pressure** → `references/pressure/rules.md`

## Guidelines

See `guidelines.md` for:
- Task → workflow mapping
- Situation → reference file mapping
- Decision tree for common scenarios

## Reference Loading Checklist

Before giving any code advice or writing code, verify:
- [ ] Identified which reference categories apply to the current task
- [ ] Loaded the `rules.md` for each applicable category
- [ ] Loaded `examples.md` if demonstrating patterns or reviewing code
- [ ] Loaded the relevant `workflow/*.md` if executing a multi-step task
- [ ] Will cite specific rules/files in recommendations