Desloppify

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

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
• defensive guards around persisted/domain state usually mean the boundary is misplaced
• clean shape: parse untrusted input once at the edge, keep trusted internal values typed, and do not re-normalize internal state downstream
• repeated ?: and ?? around domain values are a signal to inspect boundaries; if code keeps defaulting or re-normalizing persisted/internal state, validate once at the edge instead
• do not treat all ternaries/nullish coalescing as slop; target defensive fallback chains and repeated coercion, not straightforward business logic

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