Claude Commands

docs.md

Generate Technical Documentation

Target: $ARGUMENTS

Parse $ARGUMENTS as follows:

• Empty → ask what to document and what type (API reference / architecture / README / runbook / ADR)
• File path(s) or glob → document those files; infer the best doc type from content
• api <path> → API reference for that path
• arch → architecture overview for the whole project
• readme <path> → module README for that directory
• runbook <topic> → operational runbook for that topic
• adr <title> → architecture decision record with that title

Read all relevant source files before writing anything. Documentation that misrepresents the code is worse than no documentation.

Determine Scope First

Ask (or infer from context) which of these is needed:

• API reference — functions, classes, endpoints with params/returns/errors
• Architecture overview — how the system fits together
• Module / package README — purpose, usage, examples
• Runbook / operational guide — how to run, deploy, debug
• Decision record (ADR) — why something was built the way it was

Produce only what was asked for. Don't generate all types speculatively.

---

API Reference

For each public function / method / endpoint:

### functionName(param1: Type, param2: Type) → ReturnType

One-sentence description of what it does (not how).

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | string | yes | ... |
| param2 | number | no | Default: 0. ... |

**Returns**
Description of return value and shape.

**Throws / Errors**
- `ErrorType` — when this happens
- HTTP 404 — resource not found

**Example**
```lang
// minimal working example

Notes Edge cases, gotchas, deprecation notices.

Rules:
- Document behavior, not implementation.
- Examples must be minimal and actually work.
- Don't document private/internal functions unless asked.
- If a parameter's purpose isn't obvious from name + type, explain it.

---

## Architecture Overview

Structure:
1. **Purpose** — what problem does this system solve, for whom
2. **Components** — list each major component, one-line role, what it owns
3. **Data flow** — how a request / event moves through the system (use ASCII diagram if helpful)
4. **Key dependencies** — external services, databases, queues — and what fails if they're down
5. **Constraints & trade-offs** — decisions that affect future development (e.g. "single-region by design", "no background jobs — polling only")
6. **What's not here** — explicitly call out scope boundaries

---

## Module README

Structure:
```markdown
# Module Name

One-sentence description.

## What it does
2–4 sentences. No marketing language.

## When to use it (and when not to)

## Installation / Setup
Minimal steps. Real commands.

## Usage
Minimal working example first. More complex examples after.

## Configuration
Table of env vars / config options.

## API
[link to or inline API reference]

## Known limitations

---

General Rules

• Write for the reader who is new to this code but experienced in the domain.
• Concrete over abstract. Show examples before explaining principles.
• Don't explain what the language or framework does — explain what this code does.
• If the code is unclear and you're uncertain what it does, say so rather than guessing.
• Use present tense: "Returns the user object" not "Will return" or "Returns a user object that represents".
• Match the terminology used in the codebase and domain, don't introduce synonyms.
• Avoid: "simply", "just", "easy", "straightforward", "obviously".

review.md

Code Review

Target: $ARGUMENTS

If $ARGUMENTS is empty, review the current git diff (staged + unstaged). If it's a file path or glob, read those files. If it's a PR number or branch name, diff against main. If ambiguous, ask before proceeding.

Be a thorough but pragmatic reviewer. Flag real problems; don't nitpick style unless it creates risk.

Process

1. Read every file in scope fully before commenting.
2. Group findings by severity.
3. For each finding: give file path + line number, describe the problem, explain the risk, show the fix.

Review Checklist

Correctness

• Logic errors, off-by-one, wrong operator, incorrect condition
• Null/undefined/empty dereferences
• Race conditions, shared mutable state
• Wrong assumptions about data shape or API contract
• Error paths that silently swallow failures

Security (flag these prominently)

• Injection: SQL, command, path traversal, template
• XSS / output encoding
• Auth: missing checks, broken access control, privilege escalation
• Secrets or credentials in code
• Insecure defaults (HTTP, weak crypto, world-readable files)
• Unvalidated user input reaching sensitive operations

Performance

• N+1 queries or equivalent
• Unbounded loops or allocations
• Missing indexes implied by query patterns
• Unnecessary recomputation inside loops
• Blocking I/O on hot paths

Reliability

• Missing error handling at system boundaries
• Retry logic without backoff / jitter
• No timeout on external calls
• Resource leaks (file handles, DB connections, goroutines)
• Partial failure leaving state inconsistent

Maintainability

• Function / method does more than one thing
• Names that mislead or require mental mapping
• Logic duplicated rather than extracted
• Magic numbers / strings without explanation
• Deep nesting that obscures control flow
• Dead code

Tests

• New code has no tests
• Tests assert on implementation details not behavior
• Happy path only, no edge cases or error paths
• Mocks hiding real integration problems

Output Format

Use this structure:

---

Summary

One paragraph: overall quality, biggest risks, verdict (approve / approve with nits / needs changes / block).

---

Findings

🔴 Critical — [short title]

File: path/to/file.ts:42 Problem: [what's wrong and why it's dangerous] Fix:

// corrected code

🟡 Major — [short title]

...

🔵 Minor — [short title]

...

💡 Suggestion (non-blocking) — [short title]

...

---

Only include severity levels that have findings. If no issues found in a category, omit it. Don't pad the review. A clean codebase should get a short review.

smell.md

Code Smell Detection

Target: $ARGUMENTS

Parse $ARGUMENTS as follows:

• Empty → ask which files or directory to analyze
• File path(s) or glob → analyze those files
• Directory path → analyze all source files in that directory recursively
• Smell category (e.g. bloaters, couplers, complexity) → restrict findings to that category only; still ask for a target if none given

Read every file in full before reporting. Distinguish smells from bugs — smells aren't necessarily broken, but they increase the cost of change and the likelihood of future bugs.

Don't flag style preferences or framework opinions as smells. Flag structural problems with real consequences.

---

Smell Catalogue

Bloaters — things that have grown too large

• Long function/method — does more than one thing; hard to name precisely
• Large class / god object — owns too many responsibilities; hard to test in isolation
• Long parameter list — >3–4 params usually signals a missing abstraction (config object, dedicated type)
• Data clumps — same group of variables travel together everywhere; should be a type/struct
• Primitive obsession — using raw strings/ints where a named type would carry meaning and validation

Object-Orientation Abusers

• Switch/if-else on type — usually a missing polymorphism opportunity
• Refused bequest — subclass inherits but ignores or overrides most of parent; wrong hierarchy
• Alternative classes with different interfaces — two classes do the same thing with different names

Change Preventers — one change forces many others

• Divergent change — one class changed for many different reasons (violates SRP)
• Shotgun surgery — one logical change requires edits in many unrelated places
• Parallel inheritance hierarchies — adding a subclass in one hierarchy forces one in another

Dispensables — things that add noise without value

• Dead code — unreachable branches, unused variables, commented-out code
• Speculative generality — abstractions built for requirements that don't exist
• Duplicate code — same logic copy-pasted; diverges silently over time
• Lazy class — a class that doesn't do enough to justify its existence
• Data class — class with only fields and getters/setters; no behavior

Couplers — excessive entanglement

• Feature envy — a method that uses more of another class's data than its own
• Inappropriate intimacy — class accesses internals of another (bypasses encapsulation)
• Message chains — a.getB().getC().getD() — brittle to any middle change
• Middle man — class that only delegates; remove it and call the target directly

Complexity Smells

• Arrow code / deep nesting — early returns flatten this; nesting beyond 3 levels is a warning
• Boolean trap — createUser(true, false, true) — what does any of this mean?
• Magic numbers/strings — unexplained literals; should be named constants
• Inconsistent naming — same concept called different things in different places
• Leaky abstraction — callers must know internal details to use the interface correctly

---

Output Format

Summary

Overall smell burden: Low / Medium / High / Critical. One paragraph on the dominant patterns found.

---

Findings

For each smell:

[Smell Name] — path/to/file.ts (line X–Y)

What: Describe what the code is doing structurally. Why it's a problem: What future pain does this create? (harder to test, easy to introduce bugs, blocks parallelism, etc.) Refactor: Concrete suggestion — rename, extract method, introduce type, etc. Code snippet if the fix is non-obvious.

---

Smell Heatmap

At the end, list files by smell concentration (most smells first):

File	Smells	Dominant type
src/UserService.ts	5	God object, feature envy
src/utils.ts	3	Dead code, duplicate logic

---

Rules

• Don't report the same smell twice for the same root cause.
• Don't flag smells in test files that are acceptable test patterns (e.g., long setup, repeated assertions).
• If a smell is intentional and the trade-off is obvious, skip it or note it as "acknowledged trade-off".
• Prioritize smells with the highest change cost — things you'd have to touch to add any new feature.