@codename_inc/spectre 3.7.0

package/plugins/spectre/commands/clean.md

@@ -0,0 +1,313 @@
+---
+description: 👻 | Complete cleanup flow - clean, inspect, lint, test - primary agent
+---
+# 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: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.