--- name: "spectre-clean" description: "πŸ‘» | Complete cleanup flow - clean, inspect, lint, test - primary agent" user-invocable: true --- # clean ## Input Handling Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value. # clean: Analyze recent changes for dead code and artifacts from failed branches ## Description - **What** β€” Analyze a scoped working set (commit range, unstaged changes, or context window) to identify dead code, orphaned artifacts, and remnants from abandoned implementation attempts; dispatch parallel subagents to investigate and validate findings - **Outcome** β€” Clean code with all dead artifacts from recent work removed; validated removal tasks ready for execution ## Variables ### Dynamic Variables - `commit_id`: Optional starting commit - analyzes all changes **from and including this commit** through HEAD plus staged/unstaged/untracked β€” (via ARGUMENTS: $ARGUMENTS) - **INCLUDES** the commit_id commit itself and all subsequent commits through HEAD - If commit_id equals HEAD, working set will be staged + unstaged + untracked only - If commit_id is invalid or not in history, **STOP and ask user for guidance** - `scope_mode`: One of: `commit_range`, `unstaged`, `context` β€” determines working set - `target_out_dir`: Optional OUT_DIR override ### Static Variables - `out_dir`: docs/tasks/{branch_name} - `analysis_dir`: {out_dir}/cleanup_analysis - `reports_subdir`: {analysis_dir}/area_reports - `validation_subdir`: {analysis_dir}/validations - `max_parallel_agents`: 4 ## ARGUMENTS Input Optional scope specification. If ambiguous, ask user to clarify. <ARGUMENTS> $ARGUMENTS </ARGUMENTS> ## Codebase Structure **Relevant Files**: - Working set files determined by scope - `package.json` β€” Dependencies context - `tsconfig.json` β€” TypeScript configuration - `.gitignore` β€” Exclusion patterns to respect ## Instructions - **Primary goal**: Remove dead code artifacts left behind from recent work, especially failed implementation branches - Never mark production code as safe to remove without validation - Respect .gitignore patterns when analyzing files - Document uncertainty clearly; flag items requiring manual review - All file paths must be absolute from repository root - Focus on artifacts likely created during recent work: unused functions, orphaned imports, commented-out code, debug statements - **File safety**: Default filenames (`working_set.json`, `initial_findings.md`, `duplication_report.md`, `cleanup_summary.md`) must never overwrite existing filesβ€”if a target exists, create a scoped variant (append scope/task/timestamp) and use that path in messaging. - when committing, β€”no-verify and eslint-disable, or committing code with eslint-disable, is expressly forbidden without the user's explicit permission. ## Step (1/7) - Determine Working Set Scope - **Action** β€” DetermineScope: Identify which files to analyze - **If** ARGUMENTS contains `commit_id` or commit SHA: - **First**: Validate commit_id exists: `git rev-parse --verify {commit_id}^{commit} 2>/dev/null` - **If validation fails**: STOP and ask user "Commit {commit_id} is invalid or not found in history. Please provide a valid commit SHA or ref." - **Else**: proceed with discovery - Committed changes: `git log --name-only --pretty=format: {commit_id}^..HEAD | sort -u` - **IMPORTANT**: Uses `{commit_id}^..HEAD` to INCLUDE the commit_id commit itself - Staged changes: `git diff --cached --name-only` - Unstaged changes: `git diff --name-only` - Untracked files: `git ls-files --others --exclude-standard` - **Working Set** = UNION of all four sets above - **ElseIf** ARGUMENTS specifies "unstaged" or "staged": - Staged changes: `git diff --cached --name-only` - Unstaged changes: `git diff --name-only` - Untracked files: `git ls-files --others --exclude-standard` - **Working Set** = UNION of all three - **ElseIf** ARGUMENTS specifies "context" or mentions current session: - Ask user: "Which files from our current session should I analyze? List the files/directories or say 'all discussed files'" - **Wait** β€” User specifies files - **Working Set** = User-specified files - **Else** (scope ambiguous): - Ask user: "How should I scope the cleanup analysis?" - `1` β€” From a specific commit (provide SHA) - `2` β€” Current unstaged/staged changes only - `3` β€” Files we've discussed in this session - **Wait** β€” User selects scope mode - **Action** β€” RecordWorkingSet: Save working set to `{analysis_dir}/working_set.json` - Include: file list, scope mode, commit range (if applicable) - **Action** β€” DetermineOutputDir: Set output location - `branch_name=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)` - **If** user specifies `target_out_dir` β†’ `OUT_DIR={target_out_dir}` - **Else** β†’ `OUT_DIR={out_dir}` - `mkdir -p "OUT_DIR/{analysis_dir}/{reports_subdir}"` - `mkdir -p "OUT_DIR/{analysis_dir}/{validation_subdir}"` ## Step (2/7) - Analyze Working Set for Dead Code Patterns - **Action** β€” IdentifyDeadCodePatterns: Scan working set files for common dead code indicators - **Patterns to detect** (ordered by likelihood after failed branches): 1. **Orphaned imports** β€” imports with no usage in the file 2. **Unused functions/variables** β€” declared but never called/referenced 3. **Commented-out code blocks** β€” large blocks of commented code (>5 lines) 4. **Debug artifacts** β€” debugger statements, TODO/FIXME from current work 5. **Temporary logging** β€” development-time logging to remove: - console.log/warn/error without structured context (bare strings, variable dumps) - Logging inside loops or hot paths (per-iteration logging) - Debug prefixes: "DEBUG:", "TODO:", "TEMP:", "XXX:", "HACK:" - Variable dumps: `console.log(varName)`, `console.log({var1, var2})` - Checkpoint logs: "here", "got here", "reached X", "entering/exiting" - Timing logs not part of production observability - Commented-out logging statements 6. **Dead branches** β€” unreachable code paths, always-false conditions 7. **Orphaned exports** β€” exports not imported anywhere in codebase 8. **Duplicate implementations** β€” similar code suggesting abandoned refactor 9. **Test artifacts** β€” `.only`, skipped tests, test data that should be removed 10. **AI code slop** β€” patterns inconsistent with codebase style: - Excessive comments a human wouldn't add or inconsistent with file style - Unnecessary defensive checks/try-catch in trusted codepaths - Casts to `any` to bypass type issues - Over-documentation of obvious code - Verbose patterns where codebase uses concise ones - For each file in working set: identify potential issues with file:line references - **Action** β€” ChunkAnalysis: Group findings by file/module for parallel investigation - Create 2-5 investigation chunks based on working set size - Each chunk: area name, files, identified patterns, investigation focus - **Action** β€” SaveInitialFindings: Write to `{analysis_dir}/initial_findings.md` (use a scoped variant like `initial_findings_{timestamp}.md` if the default exists; never overwrite) - Include: pattern counts, file list per pattern, investigation priorities ## Step (3/7) - Analyze Duplication - **Action** β€” DetectDuplication: Find repeated code patterns in working set - **Patterns to detect**: - Copy-pasted logic (>5 similar lines, 2+ instances) - Nearly-identical functions with cosmetic differences (variable names differ, same logic) - Repeated type definitions or interfaces - Same validation/transform/fetch patterns across files - **Output per cluster**: - All instance locations (file:line) - Pattern description - Extraction recommendation (where to consolidate) - Effort estimate (low/medium/high) - Ignore intentional duplication (test fixtures, generated code) - **Action** β€” GenerateDuplicationReport: Write `{analysis_dir}/duplication_report.md` (or a scoped variant if it already exists; do not overwrite) - **Format**: ```plaintext ## Duplicate Code Clusters ### Cluster 1: {pattern_name} ({instance_count} instances) - `{file1}:{lines}` - `{file2}:{lines}` - `{file3}:{lines}` **Pattern**: {description} **Recommendation**: Extract to `{suggested_location}` **Effort**: {low|medium|high} ``` ## Step (4/7) - Dispatch Investigation Subagents - **Action** β€” PrepareSubagentPrompts: Generate investigation prompts for each chunk **Subagent Investigation Instructions Template**: ```markdown You are investigating recent changes in {area_name} for dead code artifacts. **Context**: These files were recently modified. Look for artifacts from failed implementation attempts, abandoned branches, or incomplete refactors. **Files in scope**: {file_list} **Initial patterns detected**: {patterns_for_area} **Your task**: 1. Review all files in scope thoroughly 2. For EACH potential issue, verify: - Is this code actually unused? (check imports, calls, references) - Is this a remnant from a failed approach? (check git history if needed) - Could this break something if removed? (check dependencies) 3. Categorize findings: - SAFE_TO_REMOVE: Confirmed dead code, no dependencies - NEEDS_VALIDATION: Likely dead but needs confirmation - KEEP: Actually used or unclear 4. Document evidence for each finding **Output format**: Markdown report with sections per issue type. **Critical**: Be conservative. When in doubt, mark NEEDS_VALIDATION. Save your report to: {reports_subdir}/{area_name}_report.md (if that file exists, append a unique identifier such as `{area_name}_{timestamp}.md`; never overwrite) ``` - **Action** β€” SpawnSubagents: Launch parallel investigation agents (up to {max_parallel_agents}) - For each chunk: spawn subagent with investigation prompt - Set output path: `{reports_subdir}/{area_name}_report.md` (or scoped variant if default exists) - **Wait** β€” All investigation subagents complete and save reports ## Step (5/7) - Validate High-Risk Findings - **Action** β€” ConsolidateReports: Read all investigation reports from `{reports_subdir}/` - Group findings: SAFE_TO_REMOVE, NEEDS_VALIDATION, KEEP - Extract SAFE_TO_REMOVE items involving: - Function/class deletions - File deletions - Export removals - **Action** β€” PrepareValidationPrompts: Generate validation prompts for high-risk items **Subagent Validation Instructions Template**: ```markdown You are validating a finding from dead code analysis. **Original finding**: {finding_description} {file_path}:{line_numbers} {reasoning_from_investigation} **Your task**: 1. Search codebase for ANY usage (dynamic imports, string refs, reflection) 2. Check test files for usage 3. Verify the code is actually dead, not just indirectly used 4. Determine: CONFIRMED_SAFE, UNSAFE, or UNCERTAIN **Output format**: Markdown with verdict, evidence, reasoning. Save to: {validation_subdir}/{task_id}_validation.md (if that file exists, append a unique identifier; never overwrite) ``` - **Action** β€” SpawnValidationAgents: Launch validation agents (up to {max_parallel_agents}) - **Wait** β€” All validation subagents complete ## Step (6/7) - Generate Removal Tasks, Verify & Commit - **Action** β€” ReadValidations: Load validation results from `{validation_subdir}/` - Group by verdict: CONFIRMED_SAFE, UNSAFE, UNCERTAIN - **Action** β€” ReconcileFindings: Create final removal list - CONFIRMED_SAFE β†’ approved for removal - UNSAFE β†’ document why, exclude from removal - UNCERTAIN β†’ flag for manual review - **Action** β€” GenerateSummary: Create `{analysis_dir}/cleanup_summary.md` (or a scoped variant if it already exists; do not overwrite) - Sections: - **Executive Summary**: Scope analyzed, findings count, safe removals - **Safe Removals**: List with file:line, what to remove, why it's safe - **Manual Review Required**: Items needing human decision - **Excluded Items**: What was kept and why - **Estimated Impact**: Lines of dead code to remove - **Action** β€” CreateRemovalTasks: Generate removal task files - For each CONFIRMED_SAFE: task with exact removal instructions - Save to `{analysis_dir}/removal_tasks/task_{id}.md` - **Action** β€” PresentFindings: Show user the summary and request approval - Present summary: X files analyzed, Y items safe to remove, Z need review - **Wait** β€” User approves specific tasks or all CONFIRMED_SAFE items - **Action** β€” ExecuteRemovals: Perform removals sequentially - **If**: User hasn't approved any tasks β†’ Skip execution - **Else**: For each approved task: - File deletion β†’ `rm {file_path}` - Code removal β†’ Use Edit tool to remove lines - Document change in `{analysis_dir}/changes_log.md` - **Action** β€” Verify: Run lint and tests - Run lint, fix violations - Run tests for affected areas - **If**: Tests fail β†’ Rollback change, document failure - **Else**: Confirm removal successful - **Action** β€” CommitPlanningArtifacts: Stage and commit analysis docs - Check for uncommitted files in `{out_dir}` and `{analysis_dir}`: - `working_set.json`, `initial_findings.md`, `duplication_report.md` - `cleanup_summary.md` - Area reports in `{reports_subdir}/` - Validation reports in `{validation_subdir}/` - Any other `.md` or `.json` artifacts created during this flow - **If** uncommitted planning artifacts exist: - Stage all: `git add {out_dir}/ {analysis_dir}/` - Commit: `docs(clean): add cleanup analysis artifacts for {branch_name}` - **Action** β€” CommitCodeChanges: Commit removals by type (chore/refactor/fix/test), conventional format - **Action** β€” RenderFooter: Render Next Steps via `Skill(spectre-guide)` ## Step (7/7) - ESLint Compliance Planning **Purpose**: Systematically identify tech debt from eslint-disable comments in the working set. **7a. Collect ESLint Bypasses**: ```bash grep -rn "eslint-disable\|@ts-ignore\|@ts-expect-error" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" ``` **7b. Group by Module**: Cluster findings by directory or logical module (files that import each other). **7c. For each group with β‰₯2 bypasses**, dispatch @analyst in parallel: ```plaintext Analyze ESLint bypasses in: {file_list} For each bypass: 1. Identify the disabled rule(s) 2. Understand WHY it was disabled (type issue? legacy code? third-party types?) 3. Determine the proper fix (type narrowing, interface update, refactor, etc.) Output a refactor plan: - File: path - Line: number - Rule: disabled-rule-name - Reason: why it exists - Fix: specific refactor steps - Effort: trivial / moderate / significant - Risk: low / medium / high ``` **7d. Present Refactor Summary**: - Group by effort level (trivial fixes first) - Flag high-risk items for user decision - Create actionable items for future cleanup sprints **Note**: This step is diagnostic. Actual refactoring happens in follow-up tasks, not during clean.