Desloppify

Desloppify

Use this skill for refactor passes where the main target is less code and clearer boundaries.

Primary objective:

• remove more code than you add, without regressing behavior or coverage
• make the resulting code more direct, less layered, and easier to read locally

When to Use

Trigger this skill when the user asks for:

• "desloppify"
• removing slop, boilerplate, or over-engineering
• replacing custom helpers/types/mappings with native package features
• removing TypeScript assertions and inference workarounds

Repository Overrides

Always follow repository-level agent rules (for example AGENTS.md) when they are stricter than this skill.

Value Order

During a desloppify pass, use this priority order:

1. correctness
2. simplicity
3. deletion
4. native/package-native solutions
5. reuse
6. type neatness

Interpretation:

• pragmatism is allowed only inside this ordering
• do not use "pragmatic" as a reason to add a new helper, facade, abstraction layer, or generic utility when simpler local code is sufficient
• if correctness requires added code at a boundary, offset it by deleting incidental complexity in the same area when practical

Modes

Use one mode per pass:

1. Core mode (default)

• for most desloppify requests
• optimize for speed and high signal

2. Deep mode (high-risk)

• use for auth/billing/workflows/streaming/data migrations or broad cross-layer refactors
• adds invariants, rubric, and full verification matrix

Slop Indicators

Prioritize files with:

• large modules doing multiple jobs
• custom helper stacks that wrap package-native behavior
• custom mapping layers where Zod/schema parsing would be clearer
• custom type aliases duplicating SDK/Drizzle/inference-client contracts
• repeated as assertions, especially double-casts (as unknown as)
• duplicate or near-duplicate functions that differ only in small branches
• mirrored state (ref/useState) that can be derived from existing source state
• conditional rendering that causes layout shift — if (isPending) return null or if (!data) return null for UI that occupies space. Always render a skeleton/placeholder with the same dimensions instead. return null is only acceptable for truly optional UI that doesn't affect layout (e.g. a badge that may or may not appear)
• magic string identity fallbacks — userId = x ?? y ?? "api-key" or ?? "unknown" or ?? "" where a real ID is required. If a value must exist, guard and fail; never silently degrade to a shared string that corrupts rate limits, billing, and audit trails
• permission checks missing organizationId — every hasPermission call MUST pass organizationId explicitly. Omitting it lets Better-Auth fall back to the session's activeOrganizationId, enabling cross-org access
• protectedProcedure on session-only handlers — if a handler dereferences context.user.id/.email/.name without a null check, it must use sessionProcedure (API keys have context.user = undefined)
• org-level-only API key checks — apiKey.organizationId === resource.organizationId without scope enforcement (hasKeyScope, getAccessibleWebsiteIds, hasWebsiteScope) lets any org key access any resource in the org regardless of intended restrictions

Core Mode (Default)

Apply these non-negotiables:

• prefer native SDK/npm helpers over custom helpers
• parse untrusted boundary input with Zod (or existing boundary schema)
• derive types from source-of-truth types/schemas instead of writing parallel interfaces
• remove avoidable assertions (as, especially as unknown as)
• merge/delete duplicate helpers and thin wrappers
• infer state instead of mirroring it
• keep one source of truth per concern
• replace, then delete obsolete code in same pass
• reduce concepts and lines, not just move code around
• keep behavior stable and tests green
• prefer inlining over extraction during a cleanup pass
• do not optimize for future reuse unless it clearly deletes more code than it adds
• default outcome should be negative LOC; if not, treat the pass as suspect and justify why
• if a refactor adds safety code, run a follow-up compression pass before calling the work done

Core execution order:

1. scan hotspots (duplicate helpers, assertions, manual mappings, mirrored state)
2. identify native/schema replacement primitives
3. refactor call-sites, then delete old helpers/types
4. remove any new wrapper/helper that is not strictly necessary
5. run required QA gates and report net reduction/results

Deep Mode (High-Risk)

Use this when touching sensitive or cross-layer behavior.

Track Selection (Required in Deep Mode)

Choose one or more tracks before editing:

1. UI/state track
2. API/boundary track
3. Data/Drizzle track
4. Cross-layer integration track

If multiple tracks apply, run in this order: API/boundary -> Data/Drizzle -> UI/state -> integration validation.

Invariant-First Refactor (Required in Deep Mode)

Before refactoring:

• list invariants that must remain true (contracts, ordering, auth, billing semantics, UX states)
• perform refactor
• prove invariants with tests or explicit checks

Quality Rubric (Required Before Done in Deep Mode)

Confirm all are satisfied:

• correctness: no behavior/regression drift beyond intended scope
• boundary safety: untrusted input validated at edges
• type integrity: no avoidable assertions or inference bypasses
• simplicity: fewer concepts/helpers/types than before
• test confidence: relevant verification layers executed

Required Patterns

Prefer Native Over Custom

• do not write custom utilities if package-native behavior already solves it
• avoid creating custom "normalizer" types when SDK/DB types can be derived directly
• prefer direct code at the call-site over a new shared helper when the logic is short and local

Prefer Zod Over Manual Mapping

• use z.object, z.enum, preprocess, and transform for inbound payload normalization
• infer types from schemas (z.infer) instead of parallel hand-written interfaces
• centralize shared request/response schemas where multiple call-sites parse the same shape

Drizzle Typing

• derive row types from schema:
  • typeof table.$inferSelect
  • typeof table.$inferInsert
• do not cast inserted/selected rows when derivation can model it directly

Inference Client Typing

• parse unknown JSON payloads through explicit object guards/schema helpers
• avoid structural casts of parsed responses
• keep event parsing runtime-safe and typed at the boundary

Duplicate Function Policy

• before writing a helper, search for equivalent behavior in:
  • local module
  • shared utils
  • package SDK/native APIs
• prefer deleting both helpers and writing one direct local implementation if that is simpler than introducing another shared abstraction
• if two helpers share most logic, merge to one implementation with explicit params
• delete thin wrappers that only rename args or forward calls unchanged
• no duplicate helper/functions in the same slice unless a clear boundary requires it
• if duplication remains, document why it is intentional

Anti-Abstraction Policy

During a desloppify pass, these are presumed wrong unless clearly justified:

• new facades around test doubles or mocks
• new "shared" helpers introduced only to avoid a few repeated lines
• generic parser/normalizer utilities when a local schema or direct check is clearer
• helper extraction that makes the reader jump across files for short logic

Use this rule:

• prefer a little duplication over a new abstraction
• only introduce a helper when it removes more total code and concepts than it introduces
• if the branch becomes materially larger, do another pass focused only on deletion and inlining

Assertion Policy

• forbidden: as unknown as, as any, broad structural casts to force compatibility
• allowed: as const for literal narrowing
• rare escape hatches must be documented inline with a concrete reason

State Inference Policy

• derive from strongest source first:
  • persisted/server/DB truth
  • route/query params
  • schema-validated payloads
  • local transient UI state
• avoid storing derivable values (counts, flags, filters, status labels) as mutable state
• when state must exist, store minimal primitives and derive the rest
• mirrored state is only allowed with explicit justification (performance or lifecycle boundary)

Boundary Contract Policy

• parse external input once at the boundary (query/body/headers/events/webhooks)
• pass inferred typed payloads inward; do not re-parse/re-map at each layer
• keep boundary schema close to endpoint/adapter and shared only when reused

Verification Matrix (Required in Deep Mode)

Map changed files to required test layers:

• local utility/component logic -> unit
• API handlers/data access/boundary parsing -> integration
• queue/workflow/stream/state lifecycle changes -> integration + e2e
• auth/billing/permission/routing behavior -> integration + e2e

Fast Discovery Pass

Before refactoring, run quick scans:

• duplicate candidates: repeated function names or repeated logic blocks
• assertion hotspots: as, as unknown as, broad casts
• schema drift: hand-written interfaces near existing Zod/SDK/Drizzle types
• mirrored state: watchers that only assign one variable to another

Quality Gate

After code changes (non-markdown), run:

• format/fmt
• lint
• typecheck
• unit tests
• integration tests
• e2e tests

If any layer is blocked by environment, record the exact blocker and still run all remaining layers.

Desloppify Failure Modes

Treat the pass as failing its goal if any of these are true:

• the branch adds more helpers/facades than it deletes
• net LOC increases without a narrow, concrete boundary-safety justification
• code becomes more reusable but not simpler
• local readability gets worse because logic moved into generic utilities
• the result is "cleaner architecture" but not more straightforward code

Output Checklist

Report:

1. what was deleted/replaced
2. where assertions were removed
3. net line-count impact
4. if net LOC increased, explain exactly why and what compression pass was attempted
5. duplicate helpers/functions merged or removed
6. state that is now inferred instead of mirrored
7. mode used (Core or Deep) and why
8. invariants checked and how they were validated (required in Deep mode)
9. QA results and any environment blockers