Codegen Refactor Skill

Purpose

• Improve internal quality without changing external behavior/specs (APIs, inputs/outputs, persistence formats, and the meaning of exported/public structs).
• Minimize the change surface and proceed safely in reviewable chunks.
• Proceed in a test-driven manner and match the existing code style (naming, design, structure, error handling).
• Use Serena MCP tools to “read less, find precisely, and edit accurately.”
• This is not for feature work or bug fixes. Limit scope to improving maintainability, performance, testability, and design health.

When to use

• When refactoring work is required based on an Issue.
• When the change requires attention to performance or data races (race conditions).

Deliverables (expected output)

• Tests that transition from failing → passing (conform to the generate-test skill)
• Production code that makes the tests pass

- All tests and static analysis must complete successfully

• Minimal README/comment/documentation updates (only if necessary)

Execution steps (follow this order)

0) Safety measures before changes

• Do not break existing APIs/behavior.

- Only change behavior when there is clear evidence in the Issue/README. - If a behavior change is necessary, ask for confirmation.

• Keep changes minimal. Do not do opportunistic refactors.

- If additional refactoring is needed, create a separate Issue. - Use GitHub MCP to create the Issue.

1) Identify the Issue and confirm requirements (read README + Issue)

1. Get the current branch name:

- git rev-parse --abbrev-ref HEAD

1. Extract the Issue number from the branch name (example):

- feature/issue-<issue_number>-

1. Read the Issue

- Use GitHub MCP.

1. Check README.md / CONTRIBUTING / docs for the expected usage, constraints, and compatibility.
2. Finalize acceptance criteria as bullet points and convert them into test perspectives.

- Test perspectives must follow the codegen-test skill.

If you cannot extract the Issue number, look for clues in README / Issue list / PRs / commit messages. If still unclear, ask the user which Issue should be targeted.

2) Find the project’s existing style (grep + Serena)

Goal: Match existing patterns (structs, errors, return values, naming, test style).

• First, create an “entry point” using grep / git grep:

- grep -En "keyword|TypeName|funcName" -r . - grep -En --include='.go' "keyword|TypeName|funcName" -r . - git grep -nE "keyword|TypeName|funcName" -- '.go'

• Then use Serena MCP to locate the “right place” without over-reading:

- getsymbolsoverview (high-level symbol overview) - findsymbol (jump to type/function/method definitions) - findreferencingsymbols (find call sites/usages) - Use insertaftersymbol / replacesymbol_body etc. for pinpoint edits - Avoid reading entire large files; fetch only what you need

3) Write tests first (follow the generate-test skill)

• First, add tests and confirm they fail (red).
• Test strategy:

- Table-driven tests (happy path / error cases / boundary values) - A testable design with injectable dependencies - But do not overuse interfaces. - Keep the design simple. - For external I/O, use interfaces/mocks/in-memory approaches - Do not use external modules.

• In this step, the codegen-test skill instructions are the top priority.

4) Implement (minimal changes, high performance, idiomatic Go)

Design principles

• Keep names short and unambiguous (avoid vague words or overly long compounds).
• Follow gopls / gofmt and prefer the standard library.
• Avoid nested if/else; prefer early returns and happy-path flows.
• Think about data structures before logic (improves performance and maintainability).

Performance checklist (apply as needed)

• Avoid unnecessary allocations:

- Pre-allocate slices when appropriate: make([]T, 0, n) - Estimate capacity if appending in loops

• Use map[string]struct{} for sets (no value payload)
• Aim for “zero-copy”:

- Avoid repeated []byte↔string conversions (do it once at boundaries) - Handle large data via references/slices

• Do not overuse fmt.Sprintf in hot paths; consider strings.Builder or bytes.Buffer when needed.

5) Tests, static checks, and race checks

• Run tests (including race checks):

- task go:test

• If the change might significantly impact performance, run benchmarks:

- task go:bench

6) Rules to avoid data races

• Make reads/writes to shared state explicit and protect them with one of:

- mutex / RWMutex - ownership transfer via channels - atomic (only when applicable)

• Do not share “apparently safe” maps/slices (even read-only requires careful construction timing).
• Increase reproducibility by running concurrency in tests (t.Parallel() and/or goroutines) for race-prone areas.

Final report output (keep it short)

• Output as a Markdown report:

- Filename: <issuenumber><datetime>featurereport.md

• Issue summary (acceptance criteria)
• Changes (by file)
• Added test perspectives
• Commands executed
• Performance/race considerations (if applicable)