Desloppify

<!-- desloppify-begin -->

<!-- desloppify-skill-version: 5 -->

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 in the execution queue surfaced by next. Complete them in order — next tells you what each stage expects in the --report:

desloppify next                                        # shows the next execution 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..."

For automated triage: desloppify plan triage --run-stages --runner codex (Codex) or --runner claude (Claude). Options: --only-stages, --dry-run, --stage-timeout-seconds.

Then shape the queue. The plan shapes everything next gives you — next is the execution queue, not the full backlog. Don't skip this step.

desloppify plan                          # see the living plan details
desloppify plan queue                    # compact execution queue view
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

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 — never commit health work directly to main:

git checkout -b desloppify/code-health    # or desloppify/<focus-area>
desloppify config set commit_pr 42        # link a PR for auto-updated descriptions

The loop:

# 1. Get the next item from the execution queue
desloppify next

# 2. Fix the issue in code

# 3. Resolve it (next shows the exact command including required attestation)

# 4. When you have a logical batch, commit and record
git add <files> && git commit -m "desloppify: fix 3 deferred_import findings"
desloppify plan commit-log record      # moves findings uncommitted → committed, updates PR

# 5. Push periodically
git push -u origin desloppify/code-health

# 6. 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.

3. Reference

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.

Scoring

Overall score = 25% mechanical + 75% subjective.

• Mechanical (25%): auto-detected issues — duplication, dead code, smells, unused imports, security. Fixed by changing code and rescanning.
• Subjective (75%): 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).

Reviews

Four paths to get subjective scores:

• 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. Use the blind-review workflow described in your agent overlay doc (e.g. docs/CLAUDE.md, docs/HERMES.md).

• Even moderate scores (60-80) dramatically improve overall health.

• Stale dimensions auto-surface in next — just follow the queue.

Integrity rules: Score from evidence only — no prior chat context, score history, or target-threshold anchoring. When evidence is mixed, score lower and explain uncertainty. Assess every requested dimension; never drop one.

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": "high|medium|low"
    }
  ]
}

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