desloppify

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

Maximise the strict score honestly. Your main cycle: scan → plan → execute → rescan. Follow the scan output's INSTRUCTIONS FOR AGENTS — don't substitute your own analysis.

Don't be lazy. Do large refactors and small detailed fixes with equal energy. If it takes touching 20 files, touch 20 files. If it's a one-line change, make it. No task is too big or too small — fix things properly, not minimally.

2. The Workflow

Three phases, repeated as a cycle.

Phase 1: Scan and review — understand the codebase

desloppify scan --path .       # analyse the codebase
desloppify status              # check scores — are we at target?

The scan will tell you if subjective dimensions need review. Follow its instructions. To trigger a review manually:

desloppify review --prepare    # then follow your runner's review workflow

Phase 2: Plan — decide what to work on

After reviews, triage stages and plan creation appear as queue items in next. Complete them in order:

desloppify next                                        # shows the next workflow step
desloppify plan triage --stage observe --report "themes and root causes..."
desloppify plan triage --stage reflect --report "comparison against completed work..."
desloppify plan triage --stage organize --report "summary of priorities..."
desloppify plan triage --complete --strategy "execution plan..."

Automated triage (subagent runners)

For Codex: desloppify plan triage --run-stages --runner codex For Claude: desloppify plan triage --run-stages --runner claude — then follow orchestrator instructions per stage

Options: --only-stages observe,reflect (subset), --dry-run (prompts only), --stage-timeout-seconds N (per-stage).

Then shape the queue. The plan shapes everything next gives you — don't skip this step.

desloppify plan                          # see the full ordered queue
desloppify plan reorder <pat> top        # reorder — what unblocks the most?
desloppify plan cluster create <name>    # group related issues to batch-fix
desloppify plan focus <cluster>          # scope next to one cluster
desloppify plan skip <pat>              # defer — hide from next

More plan commands:

desloppify plan reorder <cluster> top    # move all cluster members at once
desloppify plan reorder <a> <b> top     # mix clusters + findings in one reorder
desloppify plan reorder <pat> before -t X  # position relative to another item/cluster
desloppify plan cluster reorder a,b top # reorder multiple clusters as one block
desloppify plan resolve <pat>           # mark complete
desloppify plan reopen <pat>             # reopen

Phase 3: Execute — grind the queue to completion

Trust the plan and execute. Don't rescan mid-queue — finish the queue first.

Branch first. Create a dedicated branch for health work — never commit directly to main:

git checkout -b desloppify/code-health    # or desloppify/<focus-area>

Set up commit tracking. If you have a PR, link it for auto-updated descriptions:

desloppify config set commit_pr 42        # PR number for auto-updates

The loop:

1. desloppify next              ← what to fix next
2. Fix the issue in code
3. Resolve it (next shows you the exact command including required attestation)
4. When you have a logical batch, commit:
   git add <files> && git commit -m "desloppify: fix 3 deferred_import findings"
5. Record the commit:
   desloppify plan commit-log record      # moves findings uncommitted → committed, updates PR
6. Push periodically:
   git push -u origin desloppify/code-health
7. Repeat until the queue is empty

Score may temporarily drop after fixes — cascade effects are normal, keep going. If next suggests an auto-fixer, run desloppify autofix <fixer> --dry-run to preview, then apply.

When the queue is clear, go back to Phase 1. New issues will surface, cascades will have resolved, priorities will have shifted. This is the cycle.

Other useful commands

desloppify next --count 5                         # top 5 priorities
desloppify next --cluster <name>                  # drill into a cluster
desloppify show <pattern>                         # filter by file/detector/ID
desloppify show --status open                     # all open findings
desloppify plan skip --permanent "<id>" --note "reason" --attest "..." # accept debt
desloppify exclude <path>                         # exclude a directory from scanning
desloppify config show                            # show all config including excludes
desloppify scan --path . --reset-subjective       # reset subjective baseline to 0

3. Reference

How scoring works

Overall score = 40% mechanical + 60% subjective.

• Mechanical (40%): auto-detected issues — duplication, dead code, smells, unused imports, security. Fixed by changing code and rescanning.
• Subjective (60%): design quality review — naming, error handling, abstractions, clarity. Starts at 0% until reviewed. The scan will prompt you when a review is needed.
• Strict score is the north star: wontfix items count as open. The gap between overall and strict is your wontfix debt.
• Score types: overall (lenient), strict (wontfix counts), objective (mechanical only), verified (confirmed fixes only).

Subjective reviews in detail

• Local runner (Codex): desloppify review --run-batches --runner codex --parallel --scan-after-import — automated end-to-end.
• Local runner (Claude): desloppify review --prepare → launch parallel subagents → desloppify review --import merged.json — see skill doc overlay for details.
• Cloud/external: desloppify review --external-start --external-runner claude → follow session template → --external-submit.
• Manual path: desloppify review --prepare → review per dimension → desloppify review --import file.json.
• Import first, fix after — import creates tracked state entries for correlation.
• Target-matching scores trigger auto-reset to prevent gaming.
• Even moderate scores (60-80) dramatically improve overall health.
• Stale dimensions auto-surface in next — just follow the queue.

Review output format

Return machine-readable JSON for review imports. For --external-submit, include session from the generated template:

{
  "session": {
    "id": "<session_id_from_template>",
    "token": "<session_token_from_template>"
  },
  "assessments": {
    "<dimension_from_query>": 0
  },
  "findings": [
    {
      "dimension": "<dimension_from_query>",
      "identifier": "short_id",
      "summary": "one-line defect summary",
      "related_files": ["relative/path/to/file.py"],
      "evidence": ["specific code observation"],
      "suggestion": "concrete fix recommendation",
      "confidence": 
    
  

Import rules:

• findings MUST match query.system_prompt exactly (including related_files, evidence, and suggestion). Use "findings": [] when no defects found.
• Import is fail-closed: invalid findings abort unless --allow-partial is passed.
• Assessment scores are auto-applied from trusted internal or cloud session imports. Legacy --attested-external remains supported.

Import paths:

• Robust session flow (recommended): desloppify review --external-start --external-runner claude → use generated prompt/template → run printed --external-submit command.
• Durable scored import (legacy): desloppify review --import findings.json --attested-external --attest "I validated this review was completed without awareness of overall score and is unbiased."
• Findings-only fallback: desloppify review --import findings.json

Review integrity

1. Do not use prior chat context, score history, or target-threshold anchoring.
2. Score from evidence only; when mixed, score lower and explain uncertainty.
3. Assess every requested dimension; never drop one. If evidence is weak, score lower.

Reviewer agent prompt

Runners that support agent definitions (Cursor, Copilot, Gemini) can create a dedicated reviewer agent. Use this system prompt:

You are a code quality reviewer. You will be given a codebase path, a set of
dimensions to score, and what each dimension means. Read the code, score each
dimension 0-100 from evidence only, and return JSON in the required format.
Do not anchor to target thresholds. When evidence is mixed, score lower and
explain uncertainty.

See your editor's overlay section below for the agent config format.

Commit tracking & branch workflow

Work on a dedicated branch named desloppify/<description> (e.g., desloppify/code-health, desloppify/fix-smells). Never push health work directly to main.

desloppify config set commit_pr 42              # link to your PR
desloppify plan commit-log                      # see uncommitted + committed status
desloppify plan commit-log record               # record HEAD commit, update PR description
desloppify plan commit-log record --note "why"  # with rationale
desloppify plan commit-log record --only "smells::*"  # record specific findings only
desloppify plan commit-log history              # show commit records
desloppify plan commit-log pr                   # preview PR body markdown
desloppify config set commit_tracking_enabled false  # disable guidance

After resolving findings as fixed, the tool shows uncommitted work, committed history, and a suggested commit message. After committing externally, run record to move findings from uncommitted to committed and auto-update the linked PR description.

Key concepts

• Tiers: T1 auto-fix → T2 quick manual → T3 judgment call → T4 major refactor.
• Auto-clusters: related findings are auto-grouped in next. Drill in with next --cluster <name>.
• Zones: production/script (scored), test/config/generated/vendor (not scored). Fix with zone set.
• Wontfix cost: widens the lenient↔strict gap. Challenge past decisions when the gap grows.
• Score can temporarily drop after fixes (cascade effects are normal).

4. 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"

Claude Code Overlay

Use Claude subagents for subjective scoring work. Do not use --runner codex — use Claude subagents exclusively.

Review workflow

Run desloppify review --prepare first to generate review data, then use Claude subagents:

1. Prepare: desloppify review --prepare — writes query.json and .desloppify/review_packet_blind.json.
2. Launch subagents: Split the review across N parallel Claude subagents (one message, multiple Task calls). Each agent reviews a subset of dimensions.
3. Merge & import: Merge agent outputs, then desloppify review --import merged.json --manual-override --attest "Claude subagents ran blind reviews against review_packet_blind.json" --scan-after-import.

How to split dimensions across subagents

• Read dimension_prompts from query.json for dimensions with definitions and seed files.
• Read .desloppify/review_packet_blind.json for the blind packet (no score targets, no anchoring data).
• Group dimensions into 3-4 batches by theme (e.g., architecture, code quality, testing, conventions).
• Launch one Task agent per batch with subagent_type: "general-purpose". Each agent gets:
  • The codebase path and list of dimensions to score
  • The blind packet path to read
  • Instruction to score from code evidence only, not from targets
• Each agent writes output to a separate file. Merge assessments (average overlapping dimension scores) and concatenate findings.

Subagent rules

1. Each agent must be context-isolated — do not pass conversation history or score targets.
2. Agents must consume .desloppify/review_packet_blind.json (not full query.json) to avoid score anchoring.

Triage workflow

Orchestrate triage with per-stage subagents:

1. desloppify plan triage --run-stages --runner claude — prints orchestrator instructions
2. For each stage (observe → reflect → organize → enrich):
   • Get prompt: desloppify plan triage --stage-prompt <stage>
   • Launch a subagent with that prompt
   • Verify: desloppify plan triage (check dashboard)
   • Confirm: desloppify plan triage --confirm <stage> --attestation "..."
3. Complete: desloppify plan triage --complete --strategy "..." --attestation "..."