{"slug": "deburr-edge-cases-skill-make-coding-agents-systematize-their-local-code", "title": "Deburr Edge Cases Skill: Make coding agents systematize their local code", "summary": "A new structured code quality pass, 'deburr-edge-cases', helps coding agents systematically remove AI-generated cruft from branches before merge, targeting defensive checks, redundant validation, and speculative abstraction while preserving load-bearing seams.", "body_md": "| name | deburr-edge-cases |\n|---|---|\n| description | Strip AI-codegen cruft from a branch — defensive checks the type system should make unrepresentable, redundant validation, speculative abstraction, no-op wrappers — while preserving load-bearing seams. Use after a feature lands and before merge, when asked to \"simplify\", \"de-ornament\", \"remove cruft\", \"make erroneous states unrepresentable\", or \"clean up\" a diff. |\n\nA structured pass to remove accumulated cruft from a branch — particularly the failure mode\nwhere code solves, at a narrow local layer, a problem that should be addressed globally or\nstructurally. The canonical example: instead of enforcing design intent in the type system\n(making erroneous states unrepresentable), the code accumulates defensive runtime checks to\n*detect* and flag bad states that a better type would forbid at compile time.\n\nThis is a **quality** pass, not a bug hunt. Every change must be behavior-preserving, with the\nexisting test suite as the safety net. It complements a correctness-focused review (which hunts\nbugs); route bug findings there, not here. If you trip over a genuine correctness bug mid-pass,\nnote and surface it separately — do not fix it as part of this pass.\n\nA recognizable shape — an `unwrap_or`\n\n, a single-`impl`\n\ntrait — is a prompt to ask whether the\nconstruct earns its keep *here*, not a finding in itself. Reason about intent and invariants, not\nform.\n\n- After a feature branch lands, before merge — especially work assembled by several contributors or agents, which tends to accrete per-phase scaffolding that reads as cruft once the whole is in view.\n- When the user asks to \"simplify\", \"de-ornament\", \"remove cruft / ceremony / boilerplate\", \"make bad states unrepresentable\", \"tighten the types\", or \"clean up\" a set of changes.\n\n**Defensive coding the type system should forbid.** Runtime checks, branches, or asserts guarding states a tighter type would make unrepresentable — for example a tri-state`Option<bool>`\n\n, a sentinel (`\"\"`\n\n/`-1`\n\n/`0`\n\n) standing in for an`Option`\n\n/enum, a field validated on every read rather than made unconstructable-when-invalid, or a \"this can't happen\" guard.**Redundant / over-eager validation.** Re-checking an invariant already guaranteed upstream (e.g. re-validating what a parse step already proved).**Speculative generality / over-abstraction.** A trait, generic, indirection layer, config knob, or helper with a single call site and no second implementor in view. No-op wrapper methods that just forward to another method with no distinct behavior.**Ornamental error handling.** Error/diagnostic variants for conditions that cannot occur, or a fan-out of variants where one would do.**Dead-but-dressed-up scaffolding** that is*not*a deliberate, documented forward seam.\n\nDo not strip things that earn their keep. Call them out as intentional rather than flagging them:\n\n**Genuine architectural seams**: a trait that is the documented extension point for future implementors (even with one impl today), mirroring an established pattern in the codebase.**The sole enforcement point**: input validation that is the*only*guard (e.g. validating tool-call arguments when the schema is advisory and never enforced at the boundary).**Concurrency primitives** matching the actual ownership (an`AtomicBool`\n\nguard through a shared`&self`\n\ncan't be replaced by take-by-value`Option`\n\nif the caller holds`&self`\n\n).**Test seams**: a generalization (e.g. over`AsyncWrite`\n\n) that has a real second caller in tests.**Required safety rails**: a bound or check mandated by a spec/requirement is not \"added cruft\" even if the current structure makes it hard to hit — keep it.- A DI/context struct that is over-built today but has a confirmed near-term second consumer.\n\nWhen unsure whether something is cruft or load-bearing: **it is load-bearing until proven\notherwise.** Default to keeping.\n\nFinding no ornamentation is a valid and common result — especially on small or already-tight diffs. Report \"clean\" rather than inventing a finding to justify the pass.\n\nRun the steps directly, or route the fan-out and edits through whatever review/delegation process the repo otherwise follows. Keep edits one-at-a-time and behavior-preserving, and review each before moving on. Match effort to the diff: for a few files, scan and fix directly; the clustering and per-cluster fan-out below are for large, multi-author branches.\n\nCompute the cumulative branch diff against the merge base and list the changed source files, excluding generated/state files (lockfiles, task-tracker state) unless relevant. This is the review surface.\n\nPartition the changed files into coherent clusters (e.g. parse/types, registry/storage, config/state-modeling, wiring/transport). Take one cluster at a time — or, if the repo supports parallel read-only reviewers, one reviewer per cluster. For each, apply:\n\n- the precise lens above (the five ornamentation categories + the preserve list),\n- the file cluster and the specific suspects to scrutinize,\n**verify suspicious editor diagnostics against** before reporting,`cargo check --all-targets`\n\n- a consistent finding shape: one-line title; confidence (high/med/low that it's a real\nsimplification, not a behavior change);\n`file:location`\n\n; the specific cruft; a crisp remedy (prefer \"replace runtime check X with type Y\"); behavior-preserving vs. behavior-changing.\n\nSeparate **clear wins** from **judgment calls**, and name anything judged **intentional /\nload-bearing** so it is not re-litigated. The review stage reports findings only — it does not edit.\n\nMerge the findings. Drop:\n\n- anything behavior-changing that isn't clearly an improvement,\n- anything that removes a spec-required rail,\n- low-value cosmetic churn.\nKeep the type-system wins and genuine no-op removals. The headline finding is usually a single\nstructural remodel (e.g. tri-state\n`Option<bool>`\n\n→`Option<Resolved>`\n\nso the bad state is unrepresentable); the rest are small isolated cleanups.\n\nTake one finding (or one tightly-coupled pair) at a time. **Pin the exact contract** before\nediting — especially for a structural refactor, write the target type design and the invariant\ntruth-table the change must preserve, plus a test-migration map (migrate tests to the new shape;\nnever weaken assertions to pass). Execute in **increasing invasiveness**: small, isolated,\nbehavior-preserving cleanups first; the big structural remodel last, on an already-cleaned base.\nAfter each change, verify cargo and review it before moving on. If no existing test exercises the\nchanged path, the suite is not a safety net for it — add a characterization test first, or lower\nthe finding's confidence and flag the gap.\n\nBefore deleting a \"no-op\", confirm it is one. A classic trap: a `let _ = (&field, …)`\n\ndiscard or\nan `#[allow]`\n\nthat *looks* ornamental but actually suppresses a real `dead_code`\n\n/lint warning\n(e.g. `#[derive(Deserialize)]`\n\ndoes not count as a read, and `#[derive(Debug)]`\n\nis ignored by\ndead-code analysis — so fields only read via derives genuinely warn). If removing the \"cruft\"\nproduces a warning or breaks a check, **restore it and report** rather than deleting into a broken\nbuild. Don't trade ornament for a warning.\n\nRun the full check suite on the whole de-ornamented stack: `cargo fmt --check`\n\n,\n`cargo clippy --all-targets --all-features`\n\n, `cargo nextest run`\n\n, `ratchets check`\n\n. Confirm no\nassertion was weakened or deleted to make a change pass — tests that only covered genuinely-removed\ncode may go with it, but everything else must be migrated, not loosened.\n\n**Tri-state collapse → unrepresentable bad state.**`enabled: Option<bool>`\n\nrewritten`None → Some(true)`\n\nat assembly and read via`unwrap_or(false)`\n\n, then carried*dead*into a component that only exists when enabled. Fix: split the parse DTO from a resolved type; make the consumer field`Option<ResolvedConfig>`\n\nwith**no**, so \"disabled\" =`enabled`\n\nfield`None`\n\nby construction. Deletes the rewrite, the accessor, the`unwrap_or`\n\n, the dead field, and the explanatory comments that existed only to compensate for the confusing type.**Sentinel →** A helper returning an owned`Option`\n\n.`String`\n\nwith`\"\"`\n\nmeaning \"absent\", forcing a downstream`!is_empty() && …`\n\nguard. Fix: return`Option<&str>`\n\n; the guard and an allocation vanish.**Namespacing struct → free function.** A zero-field`struct FooThing;`\n\nwhose only purpose is to host one associated`fn`\n\nthat is never called on an instance and implements no trait. Fix: make it a module-level free`fn`\n\n, delete the struct/impl. (Distinguish from the*real*seam — the trait + concrete type it delegates to — which stays.)**No-op wrapper method.** A trait default`summarize()`\n\nthat just returns`self.list()`\n\n, with no override and one caller. Fix: delete it; the caller uses`list()`\n\n. Reintroduce only if a second, genuinely-distinct behavior ever materializes.\n\n- Deleting something into a compiler/clippy warning (verify first; restore if it warns).\n- Removing a spec-mandated safety bound because the current structure makes it hard to hit.\n- Stripping a documented forward seam or the sole enforcement point of an invariant.\n- Weakening or deleting test assertions to make a refactor pass — migrate them instead.\n- Doing the big structural remodel first, or batching everything into one giant unreviewable commit.\n- Treating the pass as a bug hunt — it is quality-only; route correctness findings to a dedicated bug-hunting review.", "url": "https://wpnews.pro/news/deburr-edge-cases-skill-make-coding-agents-systematize-their-local-code", "canonical_source": "https://github.com/imbue-ai/rust-bucket/blob/main/.agents/skills/deburr-edge-cases/SKILL.md", "published_at": "2026-06-28 02:44:14+00:00", "updated_at": "2026-06-28 03:04:34.065591+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/deburr-edge-cases-skill-make-coding-agents-systematize-their-local-code", "markdown": "https://wpnews.pro/news/deburr-edge-cases-skill-make-coding-agents-systematize-their-local-code.md", "text": "https://wpnews.pro/news/deburr-edge-cases-skill-make-coding-agents-systematize-their-local-code.txt", "jsonld": "https://wpnews.pro/news/deburr-edge-cases-skill-make-coding-agents-systematize-their-local-code.jsonld"}}