agentleFS
dakldakl/engram/.claude/skills/deslop/SKILL.md

deslop

Skill2 starsChanged 5 months agoMITView on GitHub

Run a metric-driven Swift quality pass — measure with `make metrics` (lizard cyclomatic complexity + function length, swiftlint if present) into metrics/quality.json, pick the top offenders, refactor under green `make build && make test` with no behaviour change, and re-run metrics to verify every change actually improved. Activates when the user types `/deslop`, when `/work` hits the deslop checkpoint, or when code feels crusty.

127 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use simple-issue-description, control-cli and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JwuthriSkill

    simple-issue-description

    Turn a rough bug report, feature request, support note, or pull request into a short, plain-language issue focused on the problem and desired behavior. Use when a contributor asks to simplify an issue, explain what a PR is for, create the corresponding issue for a PR, remove implementation detail from a report, or invokes /simple-issue-description.

    Also in 4 projects that use this

  • ElyzeSolutionsSkill

    control-cli

    Build or adapt a local harness to drive, inspect, and profile an interactive CLI or TUI without external services. Use for CLI UX checks, startup regressions, memory leaks, hangs, prompt flows, or terminal demos.

    Also in 6 projects that use this

  • JwuthriSkill

    openseo-review-web-content

    Write and review content for the OpenSEO website (web/) — blog posts, guides, feature pages, FAQs. Distills the philosophy for on-brand, useful, accurate content. Use whenever adding or editing user-facing prose in web/content or web/src.

    Also in 4 projects that use this

  • learnerLjSkill

    verify-this

    Verify a claim with fresh local evidence: restate it falsifiably, capture baseline and treatment, compare artifacts, and return VERIFIED, NOT VERIFIED, or INCONCLUSIVE.

    Also in 6 projects that use this

  • ElyzeSolutionsSkill

    control-ui

    Build or adapt a local browser/CDP harness to drive and inspect a web, IDE, or Electron UI. Use for local UI verification, screenshots, accessibility snapshots, perf profiles, visual diffs, or reproducing UI bugs.

    Also in 7 projects that use this

  • ten9876Skill

    papercuts

    Read-only AetherSDR issue triage that surfaces the UX papercuts, bugs, and regressions you can fix AND prove today with the agent automation bridge. Use when the user says $papercuts or /papercuts, or asks to "find papercuts", "what can I fix and prove today", "triage bridge-provable issues", "what UX bugs can the bridge close", "sort issues by priority I can knock out", or otherwise wants a curated, lifecycle-aware (design→code→prove) shortlist of issues — NOT the label-and-respond /triage workflow. This is the discovery step that feeds /fb. Strictly read-only: it never labels, comments, closes, or edits issues.

    Also in 4 projects that use this

  • +5 more from Jwuthri
  • Other versions127 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 127

    1. molt-bot/clawdbot★ 391ksame name
    2. novuhq/novu★ 40ksame name
    3. every-app/open-seo★ 28ksame name
    4. millionco/react-doctor★ 15ksame name
    5. jaredpalmer/kev★ 9.8ksame name
    6. joe-bell/cva★ 6.9ksame name
    7. sanity-io/sanity★ 6.4ksame name
    8. millionco/expect★ 3.6ksame name
    9. rohitg00/pro-workflow★ 2.9ksame name
    10. compozy/compozy★ 2.9ksame name

    117 more not listed

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 8 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 125 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never touch files outside the target group.

    line 28
  2. Very specific:

    Read metrics/quality.json and store the baseline.

    line 37
  3. Distinctive:

    No behaviour change. Allowed refactors: extract private helpers.

    line 53
  4. Distinctive:

    Never change observable behaviour — refactor only.

    line 56
  5. Distinctive:

    Never add or remove public API surface.

    line 57
  6. Distinctive:

    Only touch files in the target group.

    line 58
  7. Very specific:

    After each change: make build && make test (must stay green), then make metrics and re-read quality.json.

    line 65
  8. Distinctive:

    No priority 1–3 candidates remain that haven't already failed this run.

    line 71
  9. Distinctive:

    Every remaining candidate would require touching a known false positive (see Codebase notes).

    line 72
  10. Very specific:

    Trust a refactor you didn't re-measure: Every change is verified against quality.json.

    line 90
  11. Distinctive:

    Suppress lint: instead of fixing the code.

    line 91

“Common” is measured: kept by at least 6 in 10 of the 125 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/deslop — metric-driven quality-drift sweep (Swift)

Quality drift compounds quietly. When the trigger fires, the next implementer waits and this runs first. Every change must be verified against metrics — not vibes.

0. When to run

  • Counter tripped — ≥10 substantive commits since the last deslop pass:
    LAST=$(git log --extended-regexp --grep='^(refactor|fix|chore|feat)\(deslop\)' -1 --format=%H)
    git rev-list --count $LAST..HEAD --no-merges
  • User asks — /deslop typed directly, or "feels crusty".
  • End of a long /work run.

Arguments

  • --target code — only modify production code (Sources/, Engram/Engram/). Default.
  • --target tests — only modify test files (Tests/, Engram/EngramTests/, Engram/EngramUITests/).
  • --iterations N — make N successful improvements before stopping. Default: 3.

Never touch files outside the target group.

1. Baseline

make metrics      # → metrics/quality.json
make build && make test   # must be green before you start

Read metrics/quality.json and store the baseline. Print a one-line summary: code file count, total lines, mean/max complexity, top hotspot. If make build/make test is red at baseline, stop — fix or report; never deslop on a broken tree.

2. Identify offenders (orchestrator picks — this is judgment, don't delegate it)

From metrics/quality.json, for the selected target only, pick the highest-leverage issues in this priority order:

  1. hotspots.by_complexity with ccn > 4 — multiple branching paths; split or simplify.
  2. hotspots.by_length with length > 20 — functions doing several things; split by responsibility.
  3. Lint violations (if swiftlint present) — tackle the most frequent rule first. Fix the code, never suppress.
  4. Entries in DESLOP_HINTS.md (repo root, if present) — each line is a named refactor target; take the first uncompleted one.
  5. Comment ratio outliers — < 2% (underdocumented non-obvious logic) or > 30% (over-commented obvious code).

Pick the worst 3–5 (or up to --iterations). Read the full file before changing anything.

3. Refactor under green checks (delegate fixes to a subagent)

No behaviour change. Allowed refactors: extract private helpers; replace nested conditionals with guard/early-return; rename unclear identifiers to be explicit; remove redundant comments / add comments only where logic is non-obvious; fix lint by correcting code.

Hard rules:

  • Never change observable behaviour — refactor only.
  • Never add or remove public API surface.
  • Only touch files in the target group.
  • One logical change at a time, not a sweeping rewrite.

Delegate to a general-purpose subagent with a brief that pastes the offender file(s) inline and states: "No behaviour change. make build && make test must stay green. Touch only <paths>. Scope-creep budget is zero." A bug uncovered during the pass gets its own implementer brief (commit fix(deslop): ...).

4. Verify each change against metrics

After each change: make build && make test (must stay green), then make metrics and re-read quality.json.

  • Improved or held: count it as a successful iteration. Print ✓ <what changed> — <metric> before → after.
  • Got worse: revert with git checkout -- <path>, note the failed attempt, pick the next candidate. Do not count it.

Stopping conditions (stop without asking)

  • The requested number of successful iterations is complete.
  • No priority 1–3 candidates remain that haven't already failed this run.
  • Every remaining candidate would require touching a known false positive (see Codebase notes).

5. Commit

Conventional commit subject must match the deslop-counter grep:

  • refactor(deslop): ... / fix(deslop): ... / chore(deslop): ...

Body:

  • One line per metric moved (e.g. complexity max 10→7; MemoryStore.update split).
  • Offenders fixed (file:function).
  • Accepted offenders + reasoning.

Stage by path (git add <paths>), never git add .. After committing, run make build && make test && make metrics once more — all green, metrics written.

What you must NOT do

  • Behaviour change in a deslop pass. Queue it via /queue.
  • Fix every finding. Pick 3–5 / --iterations.
  • Trust a refactor you didn't re-measure. Every change is verified against quality.json.
  • Suppress lint instead of fixing the code.
  • Use git add . — stage by path.
  • Skip the commit body — future passes rely on it to reconstruct accepted offenders.
  • Run deslop mid-task. Finish the current task first.
  • Delegate offender selection. Picking is judgment (orchestrator); fixing is delegated.

Codebase notes (Swift / SwiftUI refactoring-safety; carried from handla-app)

These are lizard/SwiftUI artefacts — verify before acting on a hotspot:

<!-- learned --> Adding a helper only improves the distribution when the code it replaces is already lizard-tracked (inside a named `func`, not a SwiftUI `body` property, `@ViewBuilder` closure, or `.alert`/`.sheet` content). Adding a helper to simplify *untracked* SwiftUI modifier content adds a function without removing tracked lines → metrics regress. Verify call sites are in tracked functions first.<!-- learned --> `@ViewBuilder` computed properties score high `ccn` from `if/else` that is purely declarative layout — do not extract; the branches express view structure, not logic. Named `@ViewBuilder func` methods (parameter-taking) are different: extraction IS safe and reduces tracked length.<!-- learned --> `@Bindable var model` and `private(set)`/`@Observable` cause lizard to emit a phantom `set` entry with inflated ccn/length that maps to no real function — skip it; look at the real `init`/body.<!-- learned --> lizard can fuse consecutive `async func` declarations, attributing the second's lines to the first. Before acting on a suspicious `by_length` hotspot, count the actual lines in the file.<!-- learned --> `make test` (SwiftPM) does NOT compile the Xcode app target under `Engram/Engram/` — only `Sources/`+`Tests/`. So a refactor of an app-only function (e.g. `EngramModel.runBundledEngram`) can't be verified by `make build && make test`; it needs `make app` (xcodebuild, slow). Prefer `Sources/` hotspots; defer app-target hotspots unless you budget an app build to verify them.<!-- learned --> Tests use swift-testing (`@Test` macros), so `swift test`/`make test` prints a spurious `Executed 0 tests` line from the empty XCTest harness. Trust the swift-testing summary (`Test run with N tests ... passed`) instead — `Executed 0` does not mean tests failed to run.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.