Polish Protocol

Remove AI slop and lint errors from the current branch. Autonomous Mode: No confirmation required for cleanup tasks.

Can Be Used By Any Agent

All technical agents can invoke this skill:

• @backend-architect
• @frontend-architect
• @mobile-architect
• @qa-engineer

Critical Rules

1. ONLY remove slop: No refactoring logic, only cleanup.
2. ONLY fix lint/type errors: Do not change style preferences.
3. NEVER change logic: If a "better" way exists, ignore it. Only fix broken things.
4. NEVER touch unrelated code: Only files in git diff main...HEAD.

Slop Reference (Delete these)

• "Here is the logic" comments
• "TODO: implement this" comments (unless legitimate)
• // ... existing code ... markers
• as any type bypasses (unless absolutely necessary)
• Excessive console.log (unless for intentional logging)
• Dead code / Unused imports
• Commented-out code blocks
• Empty functions with no implementation

Workflow

Step 1: Check Git Status

git status

Error Handling:

• If not a git repo: "❌ Not a git repository. Run git init first."
• If no changes: "✅ No changes to polish. Branch is clean."

Step 2: Get Changed Files

git diff --name-only main...HEAD

Error Handling:

• If main branch doesn't exist: Try master or develop
• If command fails: Ask user for base branch name

Step 3: Identify File Types

Group files by type:

• JavaScript/TypeScript: .js, .ts, .jsx, .tsx
• Python: .py
• Other: (CSS, Markdown, etc.) - Skip or minimal cleanup

Step 4: Remove Slop

For each file:

1. Read the file
2. Identify slop patterns
3. Remove/fix them
4. Save the file

Process files in batches of 5 to avoid overwhelming the system.

Step 5: Run Linter/Type Checker

JavaScript/TypeScript:

# Get changed JS/TS files
CHANGED_JS_FILES=$(git diff --name-only main...HEAD 2>/dev/null | grep -E '\.(js|ts|jsx|tsx)$' | tr '\n' ' ')

if [ -n "$CHANGED_JS_FILES" ] && [ -f "package.json" ]; then
  # Try ESLint
  if npm list eslint >/dev/null 2>&1; then
    npx eslint --fix $CHANGED_JS_FILES
  fi
  
  # Try TypeScript
  if [ -f "tsconfig.json" ]; then
    npx tsc --noEmit
  fi
fi

Python:

# Get changed Python files
CHANGED_PY_FILES=$(git diff --name-only main...HEAD 2>/dev/null | grep -E '\.py$' | tr '\n' ' ')

if [ -n "$CHANGED_PY_FILES" ]; then
  # Try Black (formatter)
  if command -v black >/dev/null 2>&1; then
    black $CHANGED_PY_FILES
  fi

  # Try Ruff (linter)
  if command -v ruff >/dev/null 2>&1; then
    ruff check --fix $CHANGED_PY_FILES
  fi
fi

Error Handling:

• If linter not found: Skip and report
• If linter fails: Show errors and ask if user wants to continue
• If type errors exist: Report them (don't auto-fix)

Step 6: Run Prettier (if available)

# Get all changed files for formatting
CHANGED_FILES=$(git diff --name-only main...HEAD 2>/dev/null | tr '\n' ' ')

if [ -n "$CHANGED_FILES" ] && npm list prettier >/dev/null 2>&1; then
  npx prettier --write $CHANGED_FILES
fi

Step 7: Summary Report

Success:

✅ Polish Complete!

📊 Summary:
- Files processed: 12
- Slop removed: 23 instances
- Lint errors fixed: 7
- Type errors: 0

✨ Branch is clean and ready for review!

➡️ Next Steps:
1. Review changes: git diff
2. Commit: git add . && git commit -m "Polish: Remove slop and fix lint"
3. Ship it: /ship-it

With Warnings:

⚠️ Polish Complete (with warnings)

📊 Summary:
- Files processed: 12
- Slop removed: 23 instances
- Lint errors fixed: 7
- Type errors: 3 remaining

❌ Type Errors:
1. src/utils.ts:45 - Type 'string | undefined' is not assignable to type 'string'
2. src/api.ts:78 - Property 'id' does not exist on type 'User'
3. src/components/Form.tsx:120 - 'onClick' is missing in type 'ButtonProps'

➡️ Action Required:
Fix type errors manually before committing.

Error Handling Summary

Not a git repo:

• Error: "❌ Not a git repository. Initialize with: git init"
• Exit

No changes detected:

• Info: "✅ No changes to polish. Branch is clean."
• Exit

Base branch not found:

• Ask: "What's your base branch? (main/master/develop)"
• Retry with user input

Linter/Formatter not installed:

• Warn: "⚠️ [Tool] not found. Skipping [action]."
• Continue with remaining steps

Linter fails:

• Show errors
• Ask: "Continue with remaining files? (Yes/No)"

File read/write errors:

• Log: "❌ Failed to process [file]: [error]"
• Continue with next file

No slop found:

• Success: "✅ No slop detected. Code is clean!"
• Still run linter/formatter

Success Criteria

• All changed files scanned
• AI slop removed
• Lint errors fixed (or reported)
• Code formatted consistently
• Summary provided
• User knows next steps