Sculpt Code

Sculpt Code

Reshape code quality across eight dimensions. Scope to branch changes by default (git diff <base-branch>...HEAD), or accept explicit file/directory targets.

Philosophy: Write code for the next reader (human or agent). Minimize cognitive load. Prefer boring, obvious code over clever code. Every change must preserve business logic unless explicitly told otherwise.

Instructions

1. Determine scope - ask if unclear:
   • Branch diff: git diff main...HEAD --name-only
   • Staged changes: git diff --cached --name-only
   • Explicit files: user-provided list
2. Read all changed files in full before reviewing - understand existing patterns, not just the diff.
3. Review each dimension below. For each finding, cite file_path:line_number.
4. Apply fixes directly - this is a sculpting tool, not a report generator. Make the changes, show what you did.

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

Match the project's existing TODO convention. If it already uses a TODO-prefix taxonomy, follow that taxonomy; otherwise stick to a plain TODO: (plus the widely understood FIXME: / HACK:) rather than imposing a scheme the codebase hasn't adopted.

For illustration, a project that uses a TODO-prefix convention might distinguish:

• 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)
• Prune noisy, bloated comments and keep comments minimal (see the code-comments skill)
• 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

Larger refactors

For a bigger cleanup - removing accumulated engineering debt, untangling oversized modules, or collapsing duplicated logic across many files - work in small, reviewable passes rather than one sweeping diff:

1. Map before editing. Survey the messy area first: noisy modules, duplicated logic, dead code, public contracts, and the tests around them. Know what you're touching before you touch it.
2. One theme per pass. Pick a single cleanup theme at a time - delete dead code, simplify control flow, extract a helper, or modernise one stale pattern - not all at once.
3. State the behaviour and the check. Before each pass, name the current behaviour, the structural improvement, and the smallest check that proves behaviour stayed stable. Run that check after every pass.
4. Keep migrations separate. Framework migrations, dependency upgrades, and architecture moves are their own task - see /upgrade-dependencies - don't smuggle them into a refactor. Lean on a green test suite, or /characterization-tests when there isn't one, as the safety net.