update

2026-06-03 20:13:03 +00:00 · 2026-02-24 10:33:59 +01:00
parent 409acd2e08
commit 898a3c303f
1374 changed files with 290409 additions and 29187 deletions
@@ -0,0 +1,158 @@
+<!-- desloppify-begin -->
+<!-- desloppify-skill-version: 1 -->
+---
+name: desloppify
+description: >
+  Codebase health scanner and technical debt tracker. Use when the user asks
+  about code quality, technical debt, dead code, large files, god classes,
+  duplicate functions, code smells, naming issues, import cycles, or coupling
+  problems. Also use when asked for a health score, what to fix next, or to
+  create a cleanup plan. Supports 28 languages.
+allowed-tools: Bash(desloppify *)
+---
+
+# Desloppify
+
+## 1. Your Job
+
+**Improve code quality by fixing findings and maximizing strict score honestly.**
+Never hide debt with suppression patterns just to improve lenient score. After
+every scan, show the user ALL scores:
+
+| What | How |
+|------|-----|
+| Overall health | lenient + strict |
+| 5 mechanical dimensions | File health, Code quality, Duplication, Test health, Security |
+| 7 subjective dimensions | Naming Quality, Error Consistency, Abstraction Fit, Logic Clarity, AI Generated Debt, Type Safety, Contract Coherence |
+
+Never skip scores. The user tracks progress through them.
+
+## 2. Core Loop
+
+```
+scan → follow the tool's strategy → fix or wontfix → rescan
+```
+
+1. `desloppify scan --path .` — the scan output ends with **INSTRUCTIONS FOR AGENTS**. Follow them. Don't substitute your own analysis.
+2. Fix the issue the tool recommends.
+3. `desloppify resolve fixed "<id>"` — or if it's intentional/acceptable:
+   `desloppify resolve wontfix "<id>" --note "reason why"`
+4. Rescan to verify.
+
+**Wontfix is not free.** It lowers the strict score. The gap between lenient and strict IS wontfix debt. Call it out when:
+- Wontfix count is growing — challenge whether past decisions still hold
+- A dimension is stuck 3+ scans — suggest a different approach
+- Auto-fixers exist for open findings — ask why they haven't been run
+
+## 3. Commands
+
+```bash
+desloppify scan --path src/               # full scan
+desloppify scan --path src/ --reset-subjective  # reset subjective baseline to 0, then scan
+desloppify next --count 5                  # top priorities
+desloppify show <pattern>                  # filter by file/detector/ID
+desloppify plan                            # prioritized plan
+desloppify fix <fixer> --dry-run           # auto-fix (dry-run first!)
+desloppify move <src> <dst> --dry-run      # move + update imports
+desloppify resolve fixed|wontfix|false_positive "<pat>"   # classify finding outcome
+desloppify review --prepare                # generate subjective review data
+desloppify review --import file.json       # import review results
+```
+
+## 4. Subjective Reviews (biggest score lever)
+
+Score = 40% mechanical + 60% subjective. Subjective starts at 0% until reviewed.
+
+1. `desloppify review --prepare` — writes dimension definitions and codebase context
+   to `query.json`.
+
+2. **Review each dimension independently.** For best results, review dimensions in
+   isolation so scores don't bleed across concerns. If your agent supports parallel
+   execution, use it — your agent-specific overlay (appended below, if installed)
+   has the optimal approach. Each reviewer needs:
+   - The codebase path and the dimensions to score
+   - What each dimension means (from `query.json`'s `dimension_prompts`)
+   - The output format (below)
+   - Nothing else — let them decide what to read and how
+
+3. Merge assessments (average scores if multiple reviewers cover the same dimension)
+   and findings, then import:
+   ```bash
+   desloppify review --import findings.json
+   ```
+
+   Required output format per reviewer:
+   ```json
+   {
+     "assessments": { "naming_quality": 75.0, "logic_clarity": 82.0 },
+     "findings": [{
+       "dimension": "naming_quality",
+       "identifier": "short_id",
+       "summary": "one line",
+       "related_files": ["path/to/file.py"],
+       "evidence": ["specific observation"],
+       "suggestion": "concrete action"
+     }]
+   }
+   ```
+
+Need a clean subjective rerun from zero? Run `desloppify scan --path src/ --reset-subjective` before preparing/importing fresh review data.
+
+Even moderate scores (60-80) dramatically improve overall health.
+
+Integrity safeguard:
+- If one subjective dimension lands exactly on the strict target, the scanner warns and asks for re-review.
+- If two or more subjective dimensions land on the strict target in the same scan, those dimensions are auto-reset to 0 for that scan and must be re-reviewed/imported.
+- Reviewers should score from evidence only (not from target-seeking).
+
+## 5. Quick Reference
+
+- **Tiers**: T1 auto-fix, T2 quick manual, T3 judgment call, T4 major refactor
+- **Zones**: production/script (scored), test/config/generated/vendor (not scored). Fix with `zone set`.
+- **Auto-fixers** (TS only): `unused-imports`, `unused-vars`, `debug-logs`, `dead-exports`, etc.
+- **query.json**: After any command, has `narrative.actions` with prioritized next steps.
+- `--skip-slow` skips duplicate detection for faster iteration.
+- `--lang python`, `--lang typescript`, or `--lang csharp` to force language.
+- C# defaults to `--profile objective`; use `--profile full` to include subjective review.
+- Score can temporarily drop after fixes (cascade effects are normal).
+
+## 6. Escalate Tool Issues Upstream
+
+When desloppify itself appears wrong or inconsistent:
+
+1. Capture a minimal repro (`command`, `path`, `expected`, `actual`).
+2. Open a GitHub issue in `peteromallet/desloppify`.
+3. If you can fix it safely, open a PR linked to that issue.
+4. If unsure whether it is tool bug vs user workflow, issue first, PR second.
+
+## Prerequisite
+
+`command -v desloppify >/dev/null 2>&1 && echo "desloppify: installed" || echo "NOT INSTALLED — run: pip install --upgrade git+https://github.com/peteromallet/desloppify.git"`
+
+<!-- desloppify-end -->
+
+## Codex Overlay
+
+This is the canonical Codex overlay used by the README install command.
+
+1. Prefer first-class batch runs: `desloppify review --run-batches --runner codex --parallel`.
+2. The command writes immutable packet snapshots under `.desloppify/review_packets/holistic_packet_*.json`; use those for reproducible retries.
+3. Keep reviewer input scoped to the immutable packet and the source files named in each batch.
+4. Do not use prior chat context, score history, narrative summaries, issue labels, or target-threshold anchoring while scoring.
+5. Assess every dimension listed in `query.dimensions`; never drop a requested dimension. If evidence is weak/mixed, score lower and explain uncertainty in findings.
+6. Return machine-readable JSON only for review imports:
+
+```json
+{
+  "assessments": {
+    "<dimension_from_query>": 0
+  },
+  "findings": []
+}
+```
+
+7. Keep `findings` schema compatible with `query.system_prompt`.
+8. If a batch fails, retry only that slice with `desloppify review --run-batches --packet <packet.json> --only-batches <idxs>`.
+
+<!-- desloppify-overlay: codex -->
+<!-- desloppify-end -->