From 52018b1ac41c355c965437beaeafedb96fa6f4ab Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Thu, 9 Apr 2026 22:37:26 -0500 Subject: feat: add Claude Code settings to stowed dotfiles Add commands, settings, MCP config, and humanizer skill to dotfiles/common for GNU Stow management across machines. --- dotfiles/common/.claude/commands/refactor.md | 259 +++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) create mode 100644 dotfiles/common/.claude/commands/refactor.md (limited to 'dotfiles/common/.claude/commands') diff --git a/dotfiles/common/.claude/commands/refactor.md b/dotfiles/common/.claude/commands/refactor.md new file mode 100644 index 0000000..57acd5e --- /dev/null +++ b/dotfiles/common/.claude/commands/refactor.md @@ -0,0 +1,259 @@ +--- +description: Scan code for refactoring opportunities or perform targeted refactoring operations +argument-hint: "[scope: full|quick|complexity|duplication|dead-code|rename old new]" +--- + +# /refactor — Code Refactoring Skill + +Parse `$ARGUMENTS` to determine the operation: + +| Argument | Description | +|----------|-------------| +| `full` (default) | Run all scans: complexity + duplication + dead code | +| `quick` | High-severity issues only (critical/high across all scans) | +| `complexity` | Analyze code complexity: nesting, length, parameters, boolean expressions | +| `duplication` | Detect duplicated logic, clone blocks, repeated patterns | +| `dead-code` | Find unused imports, exports, unreachable code, dead feature flags | +| `rename old new` | Codebase-wide symbol rename with verification | + +If a file or directory path is included in the arguments, scope the scan to that path. Otherwise scan the project source directories (exclude vendored code, node_modules, build output, test fixtures). + +--- + +## General Rules (All Modes) + +- Refactoring changes structure, not behavior. If behavior changes, that is a fix, not a refactoring. +- Never refactor and add features in the same step. +- Run tests after each change to confirm behavior preservation. +- If tests are missing for the code being refactored, write characterization tests first. +- Commit each refactoring step individually with a message naming the specific transformation. +- Present findings to the user before making changes. Do not auto-apply without confirmation. + +--- + +## Mode: Complexity + +Scan for code that is too complex to maintain, test, or understand. + +### What to Check + +**Function length:** + +| Lines | Severity | Action | +|-------|----------|--------| +| 1-30 | OK | — | +| 31-50 | Medium | Consider splitting | +| 51-100 | High | Split recommended | +| 101+ | Critical | Split required | + +**Nesting depth:** + +| Levels | Severity | Action | +|--------|----------|--------| +| 1-2 | OK | — | +| 3 | Medium | Consider flattening | +| 4+ | High | Refactor: guard clauses, extract method | + +**Cyclomatic complexity** (count decision points: if, else if, else, case, for, while, catch, &&, ||): + +| Score | Severity | Action | +|-------|----------|--------| +| 1-5 | OK | — | +| 6-10 | Medium | Consider simplifying | +| 11-15 | High | Refactor recommended | +| 16+ | Critical | Refactor required | + +**Parameter count:** + +| Params | Severity | Action | +|--------|----------|--------| +| 0-3 | OK | — | +| 4-5 | Medium | Consider parameter object | +| 6+ | High | Use parameter object or split function | + +**Complex boolean expressions** (count operators in a single condition): + +| Operators | Severity | Action | +|-----------|----------|--------| +| 1-2 | OK | — | +| 3-4 | Medium | Extract to named predicate | +| 5+ | High | Extract required | + +### Detection Heuristics + +Use Grep to find candidates: + +- Long functions: Search for function/method definitions, then count lines to closing brace/end +- Deep nesting: Search for lines with 4+ levels of indentation inside control structures +- Complex conditions: Search for lines with 3+ `&&` or `||` operators +- Long parameter lists: Search for function signatures spanning 60+ characters in the parameter area + +### Refactoring Strategies + +Apply the simplest effective technique: + +1. **Guard clauses** — Flatten nested if/else by returning early +2. **Extract method** — Pull a named function from a block that has a comment explaining it or that does a distinct sub-task +3. **Extract predicate** — Replace complex boolean expression with a named function returning bool +4. **Parameter object** — Group related parameters into a struct/type/alist +5. **Decompose conditional** — Replace if/else branches with named functions for each branch + +--- + +## Mode: Duplication + +Scan for duplicated code that violates DRY. + +### What to Check + +**Clone blocks** (nearly identical code in multiple places): + +| Lines | Severity | Action | +|-------|----------|--------| +| 5-10 | Low | Consider extraction | +| 11-25 | Medium | Should extract | +| 26-50 | High | Must extract | +| 51+ | Critical | Extract immediately | + +**Logic duplication** — Same algorithm with minor variations (different variable names, different field access, different types). + +**Constant duplication** — Same magic number or string literal in 3+ places. + +**Pattern repetition** — Same structural pattern (setup-execute-teardown, validate-process-respond) repeated across files. + +**Error handling duplication** — Same try/catch or condition-case pattern repeated in many functions. + +### Detection Heuristics + +- Search for identical or near-identical multi-line blocks across files +- Search for the same string literal appearing in 3+ locations +- Search for functions with very similar names that suggest copy-paste origin +- Search for the same error message string in multiple places + +### Refactoring Strategies + +1. **Extract function** — Pull the duplicated block into a shared function with parameters for the varying parts +2. **Extract constant** — Replace magic numbers/strings with named constants +3. **Parameterize** — If two functions differ only in one value, merge into one function with a parameter +4. **Template method / higher-order function** — If the structure is the same but the operations differ, extract the structure and accept operations as arguments + +--- + +## Mode: Dead Code + +Find code that is never executed or referenced. + +### Step-by-step + +1. **Unused imports** — Use available tooling or grep for imports, then search for usage of each imported symbol. Language hints: + - TypeScript/JS: `tsc --noUnusedLocals --noEmit`, or ESLint `no-unused-vars` + - Python: `ruff check --select F401` or `pyflakes` + - Go: compiler catches these automatically + - Emacs Lisp: search for `(require 'X)` then grep for symbols from X + - Rust: compiler warns on dead code + +2. **Unused exports / public functions** — For each exported or public symbol, search the codebase for references. If zero references and not a public API entry point, flag it. + +3. **Unreachable code** — Look for: + - Code after unconditional return/throw/break/signal + - Branches with conditions that are always true or always false + - Functions defined but never called + - Commented-out code blocks (these should be deleted; version control has the history) + +4. **Dead feature flags** — Search for feature flag checks or environment variable guards. If the flag is always true/false in all environments, remove the dead branch. + +5. **Unused dependencies** — Compare declared dependencies against actual imports. Flag packages with zero import references. + +### Presentation + +Group findings by category with confidence levels: +- **High confidence** — Definitely unused, safe to remove +- **Medium confidence** — Likely unused, needs manual review +- **Low confidence** — Possibly unused, dynamic references may exist + +### Rules + +- Never remove code used via dynamic imports, reflection, metaprogramming, or string-based references +- Preserve public API exports in libraries +- Skip test utilities, fixtures, and dev-only code unless explicitly asked +- Remove code in small, focused commits — one category per commit +- Never remove error handling or fallback code just because it hasn't triggered yet +- Run the full test suite after each removal batch + +--- + +## Mode: Rename + +Perform a codebase-wide symbol rename. + +Parse `$ARGUMENTS` for: `rename ` + +### Step-by-step + +1. **Determine symbol type** — Variable, function, class, type, file, directory, CSS class, config key. + +2. **Find all references:** + - Source code: imports, exports, usages, type references + - Tests: descriptions, assertions, mocks, fixtures + - Configuration: env vars, config files, build scripts + - Documentation: comments, README, API docs, org files + +3. **If renaming a file:** + - Update all import/require paths referencing the old filename + - Update dynamic imports or autoloads + - Update config references (tsconfig paths, Makefile targets, load-path entries) + +4. **Preview changes** — Show every file that will be modified with the specific line changes. Highlight ambiguous matches that might be false positives. + +5. **Get confirmation** — Do not apply until the user approves. + +6. **Apply changes** across all files in a single atomic commit. + +7. **Verify** — Run tests and type checker / byte-compiler to confirm nothing broke. + +### Rules + +- Always preview before applying +- Handle case sensitivity: distinguish `myFunc`, `MyFunc`, `MY_FUNC`, `my-func` +- Do not rename inside vendored/dependency directories +- Preserve casing conventions (camelCase, PascalCase, snake_case, kebab-case) +- Check string literals that may reference the symbol (routes, error messages, logging) +- Update related names when appropriate (renaming `User` should prompt about `UserProps`, `UserSchema`, etc.) + +--- + +## Output Format + +For every finding in any scan mode, use this format: + +``` +[SEVERITY] Category — Title +File: path/to/file:line +Metric: specific measurement (e.g., "cyclomatic complexity: 18", "47 duplicated lines") +Issue: what the problem is (1-2 sentences) +Suggestion: recommended refactoring technique +``` + +Severity levels: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` + +### After All Findings + +Present a summary: + +``` +Refactoring Scan Summary +======================== +Critical: N +High: N +Medium: N +Low: N + +Quick wins (low effort, high impact): +1. ... +2. ... +3. ... + +Shall I apply any of these? (specify by number, or "all quick wins") +``` + +Do not generate a separate report file unless the user asks for one. Present findings inline in the conversation. -- cgit v1.2.3