Deburr Edge Cases

<!-- Generated by rust-bucket v0.9.7. DO NOT EDIT BY HAND. -->

Deburr: an edge-case de-ornamentation pass

A structured pass to remove accumulated cruft from a branch — particularly the failure mode where code solves, at a narrow local layer, a problem that should be addressed globally or structurally. The canonical example: instead of enforcing design intent in the type system (making erroneous states unrepresentable), the code accumulates defensive runtime checks to detect and flag bad states that a better type would forbid at compile time.

This is a quality pass, not a bug hunt. Every change must be behavior-preserving, with the existing test suite as the safety net. It complements a correctness-focused review (which hunts bugs); route bug findings there, not here. If you trip over a genuine correctness bug mid-pass, note and surface it separately — do not fix it as part of this pass.

A recognizable shape — an unwrap_or, a single-impl trait — is a prompt to ask whether the construct earns its keep here, not a finding in itself. Reason about intent and invariants, not form.

When to use

• 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.
• 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.

What counts as ornamentation

1. 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>, a sentinel (""/-1/0) standing in for an Option/enum, a field validated on every read rather than made unconstructable-when-invalid, or a "this can't happen" guard.
2. Redundant / over-eager validation. Re-checking an invariant already guaranteed upstream (e.g. re-validating what a parse step already proved).
3. 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.
4. Ornamental error handling. Error/diagnostic variants for conditions that cannot occur, or a fan-out of variants where one would do.
5. Dead-but-dressed-up scaffolding that is not a deliberate, documented forward seam.

What to PRESERVE

Do not strip things that earn their keep. Call them out as intentional rather than flagging them:

• 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 guard through a shared &self can't be replaced by take-by-value Option if the caller holds &self).
• Test seams: a generalization (e.g. over AsyncWrite) 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.

When unsure whether something is cruft or load-bearing: it is load-bearing until proven otherwise. Default to keeping.

Finding 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.

Process

Run 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.

1. Scope the diff

Compute 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.

2. Review by cluster

Partition 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:

• the precise lens above (the five ornamentation categories + the preserve list),
• the file cluster and the specific suspects to scrutinize,
• verify suspicious editor diagnostics against cargo check --all-targets before reporting,
• a consistent finding shape: one-line title; confidence (high/med/low that it's a real simplification, not a behavior change); file:location; the specific cruft; a crisp remedy (prefer "replace runtime check X with type Y"); behavior-preserving vs. behavior-changing.

Separate clear wins from judgment calls, and name anything judged intentional / load-bearing so it is not re-litigated. The review stage reports findings only — it does not edit.

3. Consolidate, dedup, triage

Merge the findings. Drop:

• anything behavior-changing that isn't clearly an improvement,
• anything that removes a spec-required rail,
• low-value cosmetic churn. Keep the type-system wins and genuine no-op removals. The headline finding is usually a single structural remodel (e.g. tri-state Option<bool> → Option<Resolved> so the bad state is unrepresentable); the rest are small isolated cleanups.