Deslop

---
name: deslop
description: Audit and harden existing codebases (especially AI-generated / vibe-coded ones) for production readiness. Use when the user asks to review, audit, clean up, harden, deslop, refactor, or fix quality issues across an existing codebase. Works in two phases — first a thorough multi-pass audit written to a structured file, then systematic fixes applied in safety-tiered order. Language-agnostic. Does NOT change business logic — only hardens, cleans, and robustifies.
---

# Deslop — Code Hardening Skill

Systematically audit and harden an existing codebase for production. Designed for AI-generated ("vibe coded") codebases that work superficially but are fragile, sloppy, or insecure under real-world conditions.

**This skill operates in two strict phases. Never mix them.**

```
Phase 1: AUDIT   →  produces  AUDIT.md  (human-reviewable, machine-parseable)
Phase 2: FIX     →  consumes  AUDIT.md  →  applies fixes in safety order
```

The user provides a codebase (directory path or repo). They may specify focus areas, exclusions, or constraints. If not specified, audit everything.

---

## Phase 1: AUDIT

**MANDATORY before starting**: Read the full audit checklist and format spec:
```
Read ~/.claude/skills/deslop/references/checklist.md     # 15-category audit checklist with specific patterns
Read ~/.claude/skills/deslop/references/audit-format.md  # Structured finding format for AUDIT.md
```

The audit runs five sequential passes. Each pass builds on the previous. Never skip a pass — thoroughness matters more than speed.

### Pass 0 — Reconnaissance

Map the codebase before judging anything. Do NOT write findings yet.

1. **Generate file tree**: `find . -type f | head -500` or equivalent. Understand the shape.
2. **Classify files**: Source, tests, configs, migrations, infra, docs, generated, vendored.
3. **Identify the stack**: Language(s), framework(s), package manager, build system, runtime.
4. **Build dependency map**: Which files import from which. Use `grep -rn "import\|require\|from\|include"` or language-specific tooling.
5. **Identify entry points**: Main files, route handlers, API endpoints, CLI entry points, event handlers.
6. **Detect existing tooling**: Check for `.eslintrc`, `pyproject.toml`, `tsconfig.json`, `.prettierrc`, `Makefile`, CI configs, etc.
7. **Run available linters**: If linters are configured, run them and capture output. If not, note this as a finding. Common commands:
   - JS/TS: `npx eslint . --format json 2>/dev/null` or `npx tsc --noEmit 2>&1`
   - Python: `python -m pylint **/*.py --output-format=json 2>/dev/null` or `python -m flake8 . 2>&1`
   - Go: `go vet ./... 2>&1`
   - Rust: `cargo clippy --message-format=json 2>/dev/null`
   - If no linter is configured, skip — don't install new tooling unless asked.
8. **Produce the codebase map**: Write a structured summary to the top of `AUDIT.md`:
   - Stack summary (language, framework, runtime)
   - File count by category
   - Module/directory architecture
   - Entry points
   - High-coupling modules (most imports in + out)
   - Linter output summary (if available)

**Output of Pass 0**: The "Codebase Overview" section of `AUDIT.md`. No findings yet.

### Pass 1 — Patterns & Consistency

Scan for mechanical quality issues that don't require deep semantic understanding. Process file-by-file, prioritizing high-coupling modules first (from Pass 0's dependency map).

**What to scan** (load `~/.claude/skills/deslop/references/checklist.md` categories 8-14):
- Naming convention violations and inconsistencies
- DRY violations — duplicated logic blocks, copy-pasted code
- Dead code — unused functions, unreachable branches, commented-out code, unused imports
- Magic numbers and hardcoded values
- Missing type annotations (for typed languages)
- Inconsistent patterns (e.g., callbacks in one file, promises in another)
- KISS/YAGNI violations — unnecessary abstractions, premature optimization
- Dependency issues — unused deps, circular imports

**Chunking strategy for large files (>500 lines)**: Read in function/class-sized chunks. Never split in the middle of a function. When analyzing a chunk, re-read the file's import header for context.

**For each finding**: Write it to `AUDIT.md` using the format from `~/.claude/skills/deslop/references/audit-format.md`.

### Pass 2 — Logic & Resilience

Trace critical paths through the code. This pass requires cross-file context.

**Start from entry points** identified in Pass 0. For each critical path:
1. Trace the happy path from input to output.
2. Then ask: what happens when each step fails?
3. Check every error handling point: is the error caught? Logged? Re-thrown? Swallowed?
4. Check edge cases: null/undefined inputs, empty collections, boundary values, concurrent access.
5. Check data validation at trust boundaries (user input, API responses, file reads, env vars).

**What to scan** (load `~/.claude/skills/deslop/references/checklist.md` categories 2-4):
- Correctness bugs: null derefs, off-by-one, race conditions, resource leaks, incorrect API usage
- Error handling: empty catches, swallowed exceptions, generic catches, missing async error handling, silent failures
- Business logic fragility: happy-path-only logic, missing edge cases, hardcoded business rules
- Regex hacks: patterns that pass test cases but fail on real-world input
- Async issues: unhandled promise rejections, missing await, callback hell without error propagation

**CRITICAL**: Do NOT flag business logic as "wrong" unless it's clearly a bug. The goal is resilience, not redesign. If you're unsure whether something is intentional behavior or a bug, flag it as `[NEEDS_CLARIFICATION]` and describe the concern.

### Pass 3 — Security

**What to scan** (load `~/.claude/skills/deslop/references/checklist.md` categories 1, 7):
- Injection: SQL injection, XSS, command injection, path traversal, SSRF
- Auth/Authz: missing checks, privilege escalation, broken session management
- Secrets: hardcoded API keys, tokens, passwords, connection strings in source
- Crypto: weak algorithms, insecure random, missing HTTPS enforcement
- Input validation: missing server-side validation, inconsistent validation across endpoints
- Data exposure: sensitive data in logs, verbose error messages to clients, PII leaks
- Dependencies: known CVE in dependencies (check lock files if present)

Use OWASP Top 10 as the mental framework. For each finding, note the CWE number if applicable.

### Pass 4 — Synthesis & Prioritization

After all passes complete:

1. **Deduplicate**: Some findings may appear in multiple passes. Merge them, keeping the most severe classification.
2. **Cross-reference**: A DRY violation might also be a security concern (divergent validation logic). Link related findings.
3. **Classify severity** for every finding:
   - **CRITICAL**: Direct security vulnerabilities, data loss risk, crashes in core paths
   - **HIGH**: Logic errors with production impact, missing auth checks, resource leaks
   - **MEDIUM**: Missing validation, performance issues, significant code smells
   - **LOW**: Minor inconsistencies, naming issues, missing docs
   - **INFO**: Style suggestions, optimization opportunities, nice-to-haves
4. **Assign fix tier** (from `~/.claude/skills/deslop/references/fix-playbook.md`):
   - **Tier 1** (safe): No behavioral change possible. Formatting, dead code removal, renaming, type annotations.
   - **Tier 2** (medium): Additive changes. Input validation, error handling, logging. Needs characterization tests.
   - **Tier 3** (high risk): Structural changes. Refactoring APIs, changing data access patterns. Needs human review.
5. **Write the executive summary** at the top of `AUDIT.md`:
   - Total findings by severity
   - Top 5 most critical issues with one-line descriptions
   - Overall assessment: is this codebase production-ready? What's the blast radius of the issues found?
   - Estimated fix effort by tier

6. **Present `AUDIT.md` to the user.** Ask if they want to proceed to Phase 2, adjust priorities, or exclude anything.

---

## Phase 2: FIX

**MANDATORY before starting**: Read the fix playbook:
```
Read ~/.claude/skills/deslop/references/fix-playbook.md  # Safety hierarchy, characterization tests, fix ordering
```

**NEVER start Phase 2 without user confirmation on the audit.** The user must review `AUDIT.md` first.

### Fix Ordering

Process findings in this exact order:
1. **Tier 1 fixes, CRITICAL severity first** → safest changes, highest impact
2. **Tier 1 fixes, remaining severities** → clear out all safe mechanical fixes
3. **Tier 2 fixes, CRITICAL severity** → write characterization tests first, then fix
4. **Tier 2 fixes, HIGH severity** → same pattern
5. **Tier 2 fixes, MEDIUM and below** → same pattern
6. **Tier 3 fixes** → flag for human review, do NOT auto-fix unless user explicitly approves each one

### Fix Protocol

For every fix:

1. **State the finding ID** (e.g., `SEC-003`) so the user can cross-reference `AUDIT.md`.
2. **For Tier 2+**: Write a characterization test FIRST that captures current behavior. Run it. It must pass.
3. **Apply the fix.** Prefer mechanical transformations (rename, extract, inline) over generative rewrites. If you're rewriting more than ~20 lines, stop and reconsider — you might be changing business logic.
4. **Run the characterization test again.** It must still pass (unless the fix intentionally changes error handling from "silent failure" to "explicit error", in which case update the test).
5. **Run existing tests** if they exist. Nothing should break.
6. **Update `AUDIT.md`**: Mark the finding as `[FIXED]` with a one-line description of what changed.

### Fix Guardrails

**NEVER do any of these during fixes:**
- Change business logic, pricing, billing, or domain rules
- Modify public API contracts (URL paths, request/response shapes, function signatures used by external callers)
- Delete or rewrite tests (you can ADD tests, never remove them)
- Install new dependencies without asking the user
- Rewrite working code just because you'd "write it differently"
- Batch-apply more than one Tier 2+ fix at a time without running tests between
- Assume you know what the user intended — when in doubt, mark `[NEEDS_CLARIFICATION]` and move on

**ALWAYS do these:**
- Keep the application in a deployable state after every individual fix
- Preserve all existing tests in passing state
- Add comments explaining WHY a fix was made (not what — the diff shows that)
- Use the project's existing code style and conventions (detected in Pass 0)
- Prefer the project's existing patterns over "better" patterns from elsewhere

### After All Fixes

1. Run the full test suite (if one exists).
2. Run linters (if configured).
3. Update `AUDIT.md` with a final status section showing: fixed count, skipped count, needs-clarification count, needs-human-review count.
4. Present the summary to the user.

---

## Handling Large Codebases

For codebases with 50+ files or 10,000+ lines:

- **Pass 0 is even more critical.** Spend extra time building the codebase map. Identify the "core" (most-connected modules) vs "periphery" (leaf modules, utilities).
- **Prioritize by connectivity.** Audit core modules first — bugs there have the largest blast radius.
- **Use scripts for mechanical scanning.** Run `bash ~/.claude/skills/deslop/scripts/scan_dead_code.sh` and `bash ~/.claude/skills/deslop/scripts/scan_patterns.sh` to accelerate Pass 1 findings. Review their output rather than manually grepping every file.
- **Use dependency mapping.** Run `bash ~/.claude/skills/deslop/scripts/scan_dependencies.sh` during Pass 0 to build the dependency graph automatically.
- **Chunk Pass 2 by critical path.** Don't try to trace every possible path. Focus on: authentication flow, main CRUD operations, payment/billing (if any), data export/import, and any path that handles sensitive data.
- **Fix periphery first.** During Phase 2, fix leaf modules before core modules. Lower blast radius, and fixes in leaf modules sometimes resolve findings in core modules (e.g., adding validation in a utility function used by core).

---

## Asking Questions

The skill should ask the user questions in these situations:
- **Before starting**: "I'll audit the codebase at `[path]`. Any areas to focus on or exclude?"
- **During Pass 2**: When you encounter something that might be intentional behavior or might be a bug, flag it as `[NEEDS_CLARIFICATION]` in the audit file and batch all clarification questions for the user between Pass 2 and Pass 3.
- **Before Phase 2**: Always. "Here's the audit. Want to proceed with fixes? Any findings to skip or reprioritize?"
- **During Tier 3 fixes**: Each one individually. "This fix would change [specific thing]. Approve?"

Never ask about Tier 1 fixes — just do them. They're safe by definition.

---

## What This Skill Is NOT

- Not a test-writing skill (though it writes characterization tests as a safety mechanism)
- Not a feature-building skill (it never adds new functionality)
- Not a migration tool (it doesn't change frameworks, languages, or architectures)
- Not a style enforcer (it uses the project's existing style, not an external standard)
- Not a replacement for manual security audit (it catches common issues but is not exhaustive)

The single goal: **make the existing codebase more robust, maintainable, and production-ready without changing what it does.**