name	description
polish-pr	Polish implementation before PR submission. Invoke after completing a task to clean comments, run formatting/linting, and ensure tests pass.

PR Polish Workflow

Execute the following steps in order. Do not proceed to the next step until the current step completes successfully.

Step 1: Identify Changed Files

1. Run git diff --name-only HEAD~1 or git status to identify files modified for this task
2. Focus only on files that are part of the current implementation

Step 2: Clean Unnecessary Comments

For each modified source file:

1. Read the file content
2. Preserve:
   • Docstrings (triple-quoted strings for modules, classes, functions)
   • TODO/FIXME comments with ticket references
   • Comments explaining non-obvious logic or workarounds
3. Remove:
   • Commented-out code
   • Redundant comments that restate what the code does (e.g., # increment counter before counter += 1)
   • Debug print statements or logging left from development
   • Placeholder comments like # do something here
4. Write the cleaned file

Step 3: Discover Available Commands

1. Read the Makefile (or makefile) in the repository root
2. Identify targets for:
   • Formatting (look for: format, fmt, black, prettier, style)
   • Linting (look for: lint, check, flake8, eslint, ruff, mypy)
   • Testing (look for: test, tests, pytest, unittest)
3. If no Makefile exists, check package.json scripts or pyproject.toml for equivalent commands

Step 4: Run Formatting

1. Execute the formatting command (e.g., make format)
2. If formatting modifies files, that's expected—no action needed

Step 5: Run Linting (Loop Until Clean)

1. Execute the linting command (e.g., make lint)
2. If linting fails:
   • Parse the error output to identify file, line, and issue
   • Fix each issue in the source files
   • Re-run linting
3. Repeat until linting passes with no errors

Step 6: Run Tests (Loop Until Passing)

1. Execute the test command (e.g., make test)
2. If tests fail:
   • Parse test output to identify failing tests and error messages
   • Determine if the failure is in test code or implementation code
   • Apply minimal fixes to resolve the failure
   • Re-run tests
3. Repeat until all tests pass

Step 7: Final Verification

1. Run formatting again to ensure fixes didn't introduce style issues
2. Run linting again to confirm clean state
3. Report summary: files cleaned, lint issues fixed, tests passing

Constraints

• Do not modify test assertions unless they are clearly incorrect
• Do not change public API signatures without explicit approval
• If a lint rule seems wrong, flag it rather than disabling the rule
• Limit fix iterations to 5 attempts per step; if still failing, report the issue and stop