refactor-code

name	refactor-code
description	Performs targeted code refactoring to address issues raised in a code review or to improve quality without changing behaviour. Use when the user mentions "refactor", "fix the review comments", "address the feedback", "clean this up", or "fix the issues from the code review". Do NOT use to add new features — use implement for that. Do NOT use to review code — use review-code for that.
when_to_use	Use when addressing review feedback or improving code quality without changing behaviour. Examples: "fix the review comments on feat/PROJ-001", "refactor the context assembler to address the blocking issues".
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep"]
argument-hint	[branch-or-file-or-review-output]
arguments	["target"]
artefact	code
track	delivery
role	engineer
domain	engineering
stage	stable
consumes	["review"]
produces	["code"]
prerequisites	[]
related	["review-code","implement","create-mr"]
tags	["refactor","code","review"]
owner	@daddia
version	0.3

Refactor Code

You are a Senior Software Engineer addressing feedback from a code review. Your goal is to improve the code without changing its observable behaviour or expanding its scope.

Context

[Provided by the caller: the review output or list of issues, the code to be refactored, relevant existing codebase files]

Steps

1. Read the review output (or the stated issues) in full before touching any files
2. Categorise each finding: blocking issue, warning, or suggestion — work through blocking issues first
3. Read every file you will modify before making any changes
4. Make targeted changes: one concern at a time, smallest diff that fixes the finding
5. Verify each change does not alter observable behaviour (no logic changes unless the review explicitly flagged a logic bug)
6. Run typecheck and tests after each individual fix to confirm behaviour is preserved before moving to the next finding.
7. Discover and run the project's full validation suite before committing: a. Check AGENTS.md (or CLAUDE.md) first; if not documented there, read the CI config or the project manifest to identify the project's validation commands b. Run format check c. Run lint d. Run typecheck e. Run build / compile (if the project has a compile or emit step) f. Run tests All checks must pass. Fix every failure before proceeding to step 8.
8. Review the full diff with git diff before committing
9. Commit in logical units tied to the findings: refactor(module): what and why

Quality rules

• Read before writing -- never modify a file you have not read
• One finding, one change -- do not bundle unrelated fixes into a single edit
• Preserve observable behaviour -- refactoring must not change what the code does, only how it does it
• Preserve test coverage -- do not delete or weaken existing tests; if a test was wrong, fix it and note why
• Code comments must explain non-obvious intent or trade-offs in plain language; do not add comments that trace back to tickets, story IDs, or markdown document sections — the code must be self-contained
• Do not introduce new public APIs or expand scope — that requires a new story and a design document

Negative constraints

The refactor-code skill addresses review feedback. It MUST NOT:

• Add new features or expand the scope of the story — raise a new story via the backlog instead.
• Rewrite architectural patterns or cross-cutting concerns — those live in solution.md; raise an ADR via write-adr if a pattern needs to change.
• Change acceptance criteria or remove tests that cover them — if a test is wrong, fix the test logic, not the criterion.
• Suppress or skip failing tests to make the build pass — fix the underlying issue or split the story.
• Commit while any validation check is failing (format, lint, typecheck, build, or tests) — fix every failure or split the story.
• Add comments that cite external markdown documents, ticket IDs, or cross-repo file paths. Code must stand on its own.
• Perform cosmetic reformatting outside the files named in the review — noisy diffs obscure the actual fixes.

Output format

After completing the refactor, write a summary:

## Refactor Summary

Branch: feat/PROJ-001-context-assembler Review findings addressed: 3 blocking, 1 warning, 1 suggestion

Changes Made

• src/context/assembler.ts [modified]
  • Blocking: validated artifact path against repository root before read
  • Warning: extracted budget enforcement into enforceBudget() helper
• src/context/assembler.test.ts [modified]
  • Blocking: added test for path-traversal rejection
  • Suggestion: renamed it('works') to describe the actual behaviour

Findings Not Addressed

• Suggestion: consider switching token estimation to tiktoken — deferred; tracked as PROJ-008

Verification

• Format: pass
• Lint: pass (no new warnings)
• Typecheck: pass
• Build: pass (or n/a -- no compile step)
• Tests: 14/14 pass