# Propose Refactoring

> Propose Refactoring Guide

- Skill: `nesalia-inc/propose-refactoring` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add nesalia-inc/propose-refactoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nesalia-inc/propose-refactoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nesalia-inc (https://skillmd.com/u/nesalia-inc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nesalia-inc/propose-refactoring

---


# Propose Refactoring Guide

Creates a GitHub issue for a refactoring idea that the user has identified. The user provides the refactoring to propose, the skill helps document it properly as an issue.

## When to Use

Use when:
- User has identified something that needs refactoring
- User wants to create an issue to track the refactoring
- User says "we should refactor X" or "propose refactoring for Y"

## Example

See [example-issue.md](./example-issue.md) for a complete example of a refactoring issue.

```
User: /propose-refactoring to transform the result type to use classes
Agent: Creates issue "[refactor]: use classes instead of plain result types"
```

For this issue, the body would be:

```markdown
## Why This Refactoring
Using plain string result types makes it difficult to attach metadata...

## Current Situation
Currently, functions return raw strings for errors...

## What Would Change
A class-based result type would enable structured error information...
```

## Process

### Step 1: Understand the Refactoring

Ask the user for clarification if needed:
- What specifically needs to change
- Why this refactoring is needed
- What files are affected (if known)

### Step 2: Analyze Impact

```bash
# If files mentioned, check them
cat path/to/file

# If not known, estimate based on user description
```

### Step 3: Create the Issue

Write body to temporary file first, then use it:

```bash
# Create temporary file with issue body
cat > /tmp/refactor-issue.md << 'EOF'
## Problem
[What is the issue? Be specific about what's wrong.]

## Why It Matters
[What are the consequences of this problem? How does it affect the team, the code, or users?]

## Current vs Expected DX (when applicable)
| Aspect | Current | Expected |
|--------|---------|----------|
| [Aspect 1] | [Current state] | [Expected state] |

## Current Situation
[What is currently there and why it's suboptimal]

## What Would Change
[What the improvement achieves, not how to implement it]

## Code Example (Required)
```language
// Current code that needs improvement
```

Co-Authored-By: martyy-code <nesalia.inc@gmail.com>
EOF

# Create issue using the file
gh issue create -t "[refactor]: <description>" --body-file /tmp/refactor-issue.md -l refactor

# Clean up temp file
rm /tmp/refactor-issue.md
```

**Important**: Always use a temp file, never pipe directly to `--body-file -`. Piping can cause formatting issues with special characters.

### Step 4: Confirm

Report the issue number and link to the user.

## Issue Template

```markdown
## Problem
[What is the issue? Be specific about what's wrong. Focus on maintenance, performance, or design debt.]

## Why It Matters
- **Maintenance:** [Impact on code maintenance]
- **Performance:** [Performance implications if any]
- **Debugging:** [Debugging challenges]
- **Consistency:** [Inconsistency issues]

## Current vs Expected DX (when applicable)
```typescript
// Current DX - [description of what's wrong]
function example() {
  // code showing current approach
}
```

```typescript
// Expected DX - [description of the improvement]
function example() {
  // code showing improved approach
}
```

## Current Situation
[What is currently there and why it's suboptimal]

## What Would Change
[What the improvement achieves, not how to implement it]

Include internal vs public API distinction if relevant (e.g., "public API unchanged, only internal implementation changes").

## Tasks
- [ ] [Task 1]
- [ ] [Task 2]
- [ ] [Task 3]

## Notes
[Any additional considerations, breaking change warnings, or implementation hints]
```

**Guidelines for Senior-Level Issues:**

- **Focus on "Why"**: Explain the impact on maintenance, performance, and design
- **Performance mention**: If relevant, note memory or speed implications
- **API stability**: Distinguish between public API (unchanged) and internal implementation
- **Tasks list**: Help contributors understand the implementation steps
- **Code examples**: Always show current vs expected in code blocks

## Quick Reference

```
User proposes:        /propose-refactoring for X to use Y
Create issue:         gh issue create -t "[refactor]: X to use Y" -l refactor
Confirm:              "Created issue #XX"
```

## Related Skills

| Skill | When to Use |
|-------|-------------|
| `/create-issue` | Generic issue creation |
| `/commit` | Implement the refactoring later |
| `/rfc` | For larger architectural refactors |