Cmd Sculpt Code

Dimensions

1. Dead Code & Surface Area

• Remove genuinely unused imports, functions, classes, and exception types
• Verify before delete: grep the entire codebase before removing anything
• Remove commented-out code older than 1 month unless marked with a TODO explaining why
• DRY threshold: extract helper only at 3+ occurrences (2 is fine as-is)
• Remove premature abstractions: factories with 1 implementation, pass-through wrappers, single-use utility classes

2. Naming & Clarity

• Names must reveal intent — no data, temp, result, x, val, info without context
• Follow the codebase's existing conventions (don't mix repo/repository, config/configuration)
• Function names describe what they do, not how
• No "hacker code" — prefer if not items: over if len(items) == 0, but never at the cost of clarity
• Boolean variables/functions read as questions: is_valid, has_permission, should_retry

3. File & Function Size

• Functions over ~50 lines → candidate for extraction
• Files over ~400 lines → candidate for splitting
• Each function should have a single clear responsibility
• If you need a comment to separate "sections" within a function, those sections are probably separate functions
• Group related functions in the same file; don't scatter them

4. Nesting & Control Flow

• Max 3 levels of nesting — flatten with early returns and guard clauses
• Prefer early returns over deeply nested if/else chains
• Extract complex conditions into named booleans or predicate functions
• Replace nested loops with comprehensions or helper functions where it improves readability (not where it obscures it)

5. Idiomatic Patterns

• Use language-native constructs (e.g., list comprehensions in Python, map/filter in JS where idiomatic)
• Follow the repo's established patterns — don't introduce new paradigms for one function
• Prefer standard library over hand-rolled equivalents
• Match error handling style to the rest of the codebase

6. Reuse Opportunities

• Check if an existing helper already does what new code is doing — grep before writing
• Identify patterns repeated across the diff that should use a shared utility
• Flag cases where a library function was reimplemented
• Constants and magic values: extract to named constants if used in more than one place

7. TODO Hygiene

Apply the project's TODO prefix standards:

• TODO: — general future work
• TODO_IMPROVE: — code quality improvements
• TODO_OPTIMIZE: — performance improvements
• TODO_TECHDEBT: — technical debt to address later
• TODO_REVISIT: — design decisions that may need revisiting
• TODO_IDEA: — potential features to consider
• TODO_IN_THIS_PR: — must complete before merge
• TODO_REMOVE_LATER: — temporary code with removal condition
• FIXME: — known bugs
• HACK: — temporary workarounds

Each TODO must include:

• What: clear description
• Why: context on why it's deferred

Add missing TODOs for: known shortcuts, deferred work, temporary workarounds, and obvious improvement opportunities spotted during review. Remove stale or resolved TODOs.

8. Readability & Cognitive Load

• Comments explain why, never what (delete # increment counter above counter += 1)
• Add a brief comment above grouped code blocks (~5+ lines doing one thing)
• Convert paragraph-style comments to bullet points when feasible
• Strategic whitespace: blank lines between logical sections
• Preserve all IMPORTANT, NOTE, CRITICAL, DEV_NOTE markers — clean up the text, not the tag
• Keep links, issue references, and external references intact

Output Format

For each file changed, show:

### file_path

**Changes made:**
- [dimension] description of change (line X)
- [dimension] description of change (line Y)

End with a summary: files touched, lines removed, TODOs added/removed, helpers extracted.

What NOT to Change

• Working abstractions (even if currently simple)
• Type hints (always valuable)
• Test code (unless explicitly asked)
• Forward-looking base classes if second implementation is likely soon
• Domain-specific patterns the team uses intentionally