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:

## 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:

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:

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: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:

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:

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.