|
| 1 | +--- |
| 2 | +name: slop-detector |
| 3 | +description: Structural risk scanner for AI-assisted code using AI-SLOP Detector CLI. Triggers on /slop (full project scan), /slop-file [path] (single file), /slop-gate (CI hard gate), /slop-spar (adversarial validation). Interprets findings, prioritizes fixes, and drives the scan -> patch -> re-scan -> gate quality loop. Use when asked to check code quality, detect AI slop, validate imports, review structural integrity, or run a quality gate on Python/JS/Go files. |
| 4 | +--- |
| 5 | + |
| 6 | +# AI-SLOP Detector Skill |
| 7 | + |
| 8 | +Structural risk scanner for AI-assisted code. Runs `slop-detector` CLI commands, interprets 4D scoring output (LDR + ICR + DDC + Purity), and drives the `scan -> patch -> re-scan -> gate` quality loop. |
| 9 | + |
| 10 | +## Prerequisites |
| 11 | + |
| 12 | +```bash |
| 13 | +pip install ai-slop-detector # core |
| 14 | +pip install "ai-slop-detector[js]" # optional: JS/TS |
| 15 | +pip install "ai-slop-detector[go]" # optional: Go |
| 16 | +``` |
| 17 | + |
| 18 | +Verify: `slop-detector --version` |
| 19 | + |
| 20 | +--- |
| 21 | + |
| 22 | +## Commands |
| 23 | + |
| 24 | +### /slop — Full Project Scan |
| 25 | + |
| 26 | +```bash |
| 27 | +slop-detector --project . --json |
| 28 | +``` |
| 29 | + |
| 30 | +**Workflow:** |
| 31 | +1. Run the command above from the project root |
| 32 | +2. Parse JSON: iterate `file_results[]` |
| 33 | +3. Group by `status`: CRITICAL_DEFICIT first, then INFLATED_SIGNAL, SUSPICIOUS |
| 34 | +4. For each flagged file: report path, deficit_score, top pattern issues, metric warnings |
| 35 | +5. Show project aggregate: overall status, avg_ldr, avg_ddc, structural_coherence |
| 36 | +6. Propose a prioritized patch plan (see Patch Guidance below) |
| 37 | + |
| 38 | +**Output format:** |
| 39 | +``` |
| 40 | +[SCAN RESULTS] |
| 41 | +Project: <path> | Status: <OVERALL> | Files: <N> | Flagged: <M> |
| 42 | +
|
| 43 | +CRITICAL_DEFICIT (<count>): |
| 44 | + <file> | score: <X> | patterns: <list> | ldr: <X> ddc: <X> |
| 45 | +
|
| 46 | +INFLATED_SIGNAL (<count>): |
| 47 | + ... |
| 48 | +
|
| 49 | +Recommended fixes: [ordered list] |
| 50 | +``` |
| 51 | + |
| 52 | +--- |
| 53 | + |
| 54 | +### /slop-file [path] — Single File Analysis |
| 55 | + |
| 56 | +```bash |
| 57 | +slop-detector <path> --json |
| 58 | +``` |
| 59 | + |
| 60 | +**Workflow:** |
| 61 | +1. Run on the specified file |
| 62 | +2. Report: status, deficit_score, ldr_score, inflation_score, ddc usage_ratio |
| 63 | +3. List each pattern issue with severity and line reference if available |
| 64 | +4. Explain WHY each metric is flagged (not just the score) |
| 65 | +5. Provide concrete fix for each HIGH/CRITICAL pattern |
| 66 | + |
| 67 | +**Explain metrics:** |
| 68 | +- `ldr_score < 0.30` -> "Less than 30% of lines are executable logic. Heavy padding or empty stubs." |
| 69 | +- `inflation_score > 1.0` -> "Jargon density exceeds threshold. Unjustified quality claims detected." |
| 70 | +- `ddc usage_ratio < 0.50` -> "More than half of imported modules are unused. Possible phantom imports." |
| 71 | +- `purity < 0.60` -> "Multiple critical patterns detected. AND-gate score pulled down." |
| 72 | + |
| 73 | +--- |
| 74 | + |
| 75 | +### /slop-gate — CI Gate Decision |
| 76 | + |
| 77 | +```bash |
| 78 | +slop-detector --project . --ci-mode hard --ci-report |
| 79 | +``` |
| 80 | + |
| 81 | +**Workflow:** |
| 82 | +1. Run the command; capture exit code |
| 83 | +2. Exit 0 = PASS. Exit non-zero = FAIL. |
| 84 | +3. Report: PASS/FAIL, files exceeding threshold, critical pattern counts |
| 85 | +4. On FAIL: list blocking files with deficit_score >= 70 or critical_patterns >= 3 |
| 86 | +5. Suggest minimum fixes required to unblock the gate |
| 87 | + |
| 88 | +**Gate thresholds (hard mode):** |
| 89 | +- deficit_score >= 70 -> blocks |
| 90 | +- critical_pattern_count >= 3 -> blocks |
| 91 | + |
| 92 | +--- |
| 93 | + |
| 94 | +### /slop-spar — Adversarial Validation |
| 95 | + |
| 96 | +```bash |
| 97 | +fhval spar |
| 98 | +``` |
| 99 | + |
| 100 | +Options: |
| 101 | +```bash |
| 102 | +fhval spar --layer a # known-pattern anchors |
| 103 | +fhval spar --layer b # metric boundary probes |
| 104 | +fhval spar --layer c # existence probes |
| 105 | +``` |
| 106 | + |
| 107 | +**Workflow:** |
| 108 | +1. Run full 3-layer check |
| 109 | +2. Report any calibration drift detected |
| 110 | +3. Flag dimensions where metric claims diverge from measured behavior |
| 111 | +4. If drift found: recommend `slop-detector . --self-calibrate --apply-calibration` |
| 112 | + |
| 113 | +--- |
| 114 | + |
| 115 | +## Status Interpretation |
| 116 | + |
| 117 | +| Status | Score | Action | |
| 118 | +|---|---|---| |
| 119 | +| `CLEAN` | < 30 | No action needed | |
| 120 | +| `SUSPICIOUS` | 30-50 | Review flagged patterns; low urgency | |
| 121 | +| `INFLATED_SIGNAL` | 50-70 | Fix before merge; likely AI padding | |
| 122 | +| `CRITICAL_DEFICIT` | >= 70 | Block merge; structural issue confirmed | |
| 123 | + |
| 124 | +--- |
| 125 | + |
| 126 | +## Patch Guidance — Per Pattern |
| 127 | + |
| 128 | +| Pattern | Fix | |
| 129 | +|---|---| |
| 130 | +| `not_implemented` / `pass_placeholder` | Implement the function body or remove the stub | |
| 131 | +| `phantom_import` | Remove import; if needed, install the actual package | |
| 132 | +| `empty_except` | Add specific exception type and handling logic | |
| 133 | +| `god_function` | Decompose into focused units (<= 50 lines each) | |
| 134 | +| `function_clone_cluster` | Extract shared logic into a single helper | |
| 135 | +| `dead_code` | Delete unreachable branches | |
| 136 | +| `todo_comment` / `fixme_comment` | Resolve or file a tracked issue; remove inline comment | |
| 137 | +| `star_import` | Replace with explicit named imports | |
| 138 | +| `placeholder_variable_naming` | Rename single-letter params to descriptive names | |
| 139 | +| `return_constant_stub` | Return computed value or raise NotImplementedError | |
| 140 | + |
| 141 | +--- |
| 142 | + |
| 143 | +## Scan -> Patch -> Re-scan Loop |
| 144 | + |
| 145 | +``` |
| 146 | +1. /slop -- baseline scan; identify top offenders |
| 147 | +2. Review findings -- prioritize CRITICAL_DEFICIT files |
| 148 | +3. Apply patches -- use Patch Guidance above |
| 149 | +4. /slop-file <path> -- verify each patched file |
| 150 | +5. /slop -- confirm project aggregate improved |
| 151 | +6. /slop-gate -- gate decision before merge |
| 152 | +``` |
| 153 | + |
| 154 | +**Delta reporting:** After re-scan, compare `deficit_score` before vs. after for each patched file. Report improvement or regression. |
| 155 | + |
| 156 | +--- |
| 157 | + |
| 158 | +## Self-Calibration (when scores seem off) |
| 159 | + |
| 160 | +```bash |
| 161 | +slop-detector . --self-calibrate # preview recommended weights |
| 162 | +slop-detector . --self-calibrate --apply-calibration # write to .slopconfig.yaml |
| 163 | +``` |
| 164 | + |
| 165 | +Triggers automatically after 10 re-scanned files per project. Domain-anchored (+-0.15 from profile baseline). Use when false-positive rate feels high for your project type. |
| 166 | + |
| 167 | +--- |
| 168 | + |
| 169 | +## Domain Profiles |
| 170 | + |
| 171 | +```bash |
| 172 | +slop-detector --init # auto-detect domain |
| 173 | +slop-detector --init --domain data_science # explicit override |
| 174 | +``` |
| 175 | + |
| 176 | +Profiles: `general`, `web_frontend`, `data_science`, `cli_tool`, `library`, `ml_research`, `backend_api`, `scientific` |
| 177 | + |
| 178 | +--- |
| 179 | + |
| 180 | +## Scoring Model Reference |
| 181 | + |
| 182 | +``` |
| 183 | +purity = exp(-0.5 x n_critical_patterns) |
| 184 | +GQG = exp( sum(w_i * ln(dim_i)) / total_w ) -- weighted geometric mean |
| 185 | +deficit_score = 100 * (1 - GQG) + pattern_penalty |
| 186 | +total_w = w_ldr + w_inflation + w_ddc + w_purity -- self-normalizing |
| 187 | +``` |
| 188 | + |
| 189 | +Default weights: `ldr=0.40, inflation=0.30, ddc=0.30, purity=0.10` (sum=1.10; normalized by total_w) |
| 190 | +Project aggregation: `0.6 * min + 0.4 * mean` (SR9 conservative) |
0 commit comments