/specs-code-cleanup

name: specs-code-cleanup
description: "Provides final code cleanup after task review approval. Removes debug logs, temporary comments, dead code, optimizes imports, and improves readability. Use when asked to clean up code, polish, finalize, tidy up, remove technical debt, or prepare code for completion after review. Not for refactoring logic or fixing bugs—focused solely on cosmetic and hygiene cleanup."
allowed-tools: Task, Read, Write, Edit, Bash, Grep, Glob, TodoWrite, AskUserQuestion

Code Cleanup

Overview

Performs post-review cosmetic cleanup to make code production-ready. This workflow is now integrated as Phase T-7 of `/developer-kit-specs:specs.task-implementation`. It can also be invoked manually using `--action=cleanup`.

**Input**: `docs/specs/[id]/tasks/TASK-XXX.md` (reviewed status) **Output**: Cleaned code, task marked `completed`

When to Use

• Use when asked to clean up code, polish, finalize, tidy up, or remove technical debt after review approval.
• Use to prepare code for completion: remove debug logs, dead code, optimize imports, and improve readability.
• Use as the final quality gate in the specification-driven development workflow.
• Not for refactoring logic or fixing bugs — focused solely on cosmetic and hygiene cleanup.

Arguments

| Argument | Required | Description | |----------|----------|-------------| | `--lang` | No | `java`, `spring`, `typescript`, `nestjs`, `react`, `python`, `general` | | `--task` | Yes | Path to task file | | `--action`| No | Set to `cleanup` for manual invocation |

Best Practices

• **Clean, not change**: Only remove or reorganize — never change functionality
• **Preserve behavior**: Code must work exactly the same after cleanup
• **Use project tools**: Prefer `./mvnw spotless:apply`, `npm run lint:fix`, `black`, etc.
• **Use TodoWrite**: Track progress through all 8 phases
• **Stop on failure**: If tests fail, stop and report — do not proceed

See `references/language-patterns.md` for language-specific formatter commands, import ordering, and grep patterns.

Instructions

Phase 1: Task Verification

1. Parse `$ARGUMENTS` for parameters:

• `--lang` (optional): Target language/framework
• `--task` (required): Task ID or file path
• `--spec` (optional): Spec folder path (used with task ID)

**Support two formats**:

• Format 1 (direct path): `--task=docs/specs/001-feature/tasks/TASK-001.md`
• Format 2 (spec+task): `--spec=docs/specs/001-feature --task=TASK-001`

If Format 2 is used, construct the task file path as: `{spec}/tasks/{task}.md`

2. Read the task file. Verify:

• Status is `reviewed` or `implemented` (not `completed`)
• Review report `TASK-XXX--review.md` exists and is approved

3. If not reviewed → stop and tell user to run `/developer-kit-specs:specs.task-review` first 4. Extract task ID, title, and `provides` files

Phase 2: Identify Files to Clean

1. Read `TASK-XXX--review.md` for files created/modified 2. Read task `provides` field for file paths 3. Verify files exist; build cleanup list 4. Categorize: source files, test files, config files

Phase 3: Technical Debt Removal

Search files for temporary/debug artifacts with Grep:

• `console.log`, `System.out.println`, `print(`, `// DEBUG:`, `// temp`, `// hack`
• Resolved `TODO`/`FIXME` comments (keep unresolved ones)

Review context for each finding. Remove confirmed debt and document what was removed.

Phase 4: Import Optimization

1. Run language-specific import optimizer if available (see references) 2. Manually remove unused imports if no tool exists 3. Document files changed

Phase 5: Code Readability Improvements

1. Run language-specific formatter if available (see references) 2. If no formatter: fix indentation, break long lines (>120), fix spacing 3. Remove dead code only if obviously safe 4. Document changes

Phase 6: Documentation Verification

1. Verify class/file headers and public API docs 2. Check remaining TODOs are still valid and have context 3. Remove or update outdated comments 4. Document documentation changes

Phase 7: Final Verification

1. Run linters if available 2. Run tests if available 3. Verify no logic or signature changes were introduced 4. If tests fail → stop and report failures

Phase 8: Task Completion

1. **Auto-update task status**:

• Add a `## Cleanup Summary` section to the task file
• Check any remaining boxes in the DoD section
• Hooks automatically update status to `completed` and set `completed_date` + `cleanup_date`

2. Append `## Cleanup Summary` to task file with:

• Files cleaned
• Changes made
• Verification checklist (linters, tests, no functionality changes)

3. Mark all todos complete

Examples

Spring Boot Cleanup

/developer-kit-specs:specs.task-implementation --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-001.md" --action=cleanup

Actions: 1. Verify TASK-001 status is `reviewed` 2. Files: `UserController.java`, `UserService.java`, `UserRepository.java` 3. Remove 5 `System.out.println` and 2 resolved TODOs 4. Run `./mvnw spotless:apply` 5. Run `./mvnw test -q` 6. Mark task `completed`

TypeScript Cleanup

/developer-kit-specs:specs.task-implementation --lang=typescript --task="docs/specs/002-dashboard/tasks/TASK-003.md" --action=cleanup

Actions: 1. Verify TASK-003 status is `reviewed` 2. Files: `Dashboard.tsx`, `useDashboard.ts`, `Dashboard.test.tsx` 3. Remove 8 `console.log` statements 4. Run `npm run lint:fix` and `npm run format` 5. Run `npm test` 6. Mark task `completed`

Constraints and Warnings

• Never change logic or signatures during cleanup
• Stop immediately and report if tests fail
• Verify behavior is unchanged before marking complete