Ultra Clean

Ultra Clean

Turn broad cleanup requests into a disciplined audit plus implementation pass. Default to evidence first, deletion second, abstraction third.

Core Rules

• Treat cleanup as behavior-preserving refactor work unless the user explicitly asks for product changes.
• Build repo context before editing anything: structure, languages, package manager, validation commands, generated code, framework entry points, and public interfaces.
• Run eight cleanup lanes. If the platform caps concurrent subagents, run them in waves, but keep the lane boundaries intact.
• Require every lane to produce: a critical assessment, concrete evidence, a recommendation set, implemented high-confidence fixes, and a validation note.
• Implement only high-confidence changes. Log medium-confidence ideas without changing code.
• Prefer removal over abstraction, and prefer simplification over cleverness.
• Never trust one signal alone for deletion or consolidation. Cross-check tool output with code search, runtime entry points, tests, and public API surfaces.
• Do not revert unrelated user changes. Work with the current tree as found.

Execution Workflow

1. Build a baseline.
2. Spawn one subagent per lane. Use explorer-style agents for research and worker-style agents for isolated edits when available.
3. Have each lane gather evidence first, then write a critical assessment and recommendations before editing.
4. Merge overlapping findings centrally before implementation, especially across shared types, unused code, fallback removal, and cycle breaking.
5. Implement high-confidence changes lane by lane or in small integrated batches.
6. Run focused validation after each meaningful batch, then run repo-level validation at the end.
7. Report what changed, what was intentionally left alone, and what still looks risky.

Baseline Pass

Before lane work starts:

• Map the repository and ignore generated, vendored, compiled, or external mirrors.
• Identify the canonical validation commands: tests, lint, typecheck, build, and any framework-specific checks.
• Identify reflective or non-obvious entry points before deleting anything:
  • Next.js pages, API routes, loaders, config-based hooks
  • CLI command registries
  • dependency injection containers
  • plugin systems
  • string-based imports or runtime resolution
  • serializers, migrations, RPC handlers, task runners
• Mark high-risk boundaries:
  • public APIs
  • persistence schemas
  • network input/output
  • auth and permission checks
  • error boundaries
  • cross-package contracts

Read references/baseline.md and references/report-template.md before coordinating the lanes.

Lane Ownership

Run all eight lanes:

1. Deduplicate and consolidate code only when DRY reduces complexity. Reference: references/lane-1-dedupe.md
2. Consolidate shared type definitions and contracts. Reference: references/lane-2-shared-types.md
3. Remove provably unused code with tool-assisted confirmation. Reference: references/lane-3-unused-code.md
4. Break circular dependencies with minimal architectural movement. Reference: references/lane-4-circular-deps.md
5. Replace weak types with strong, researched types. Reference: references/lane-5-strong-types.md
6. Remove unnecessary try/catch and defensive fallback logic. Reference: references/lane-6-error-handling.md
7. Delete deprecated, legacy, compatibility, and fallback paths. Reference: references/lane-7-legacy-code.md
8. Remove AI slop, stubs, larp, and unhelpful comments. Reference: references/lane-8-comment-hygiene.md

Suggested Lane Order

Use this default order unless the repo suggests a better sequence:

1. Baseline and validation discovery
2. Lane 4: circular dependencies
3. Lane 2: shared types
4. Lane 5: strong types
5. Lane 1: dedupe and consolidation
6. Lane 3: unused code
7. Lane 7: legacy and fallback removal
8. Lane 6: defensive error-handling cleanup
9. Lane 8: comment and slop cleanup

Reasoning:

• Cycles distort import boundaries and often block the cleanest dedupe or typing changes.
• Shared types should settle before stronger typing and before duplicate cleanup creates new contracts.
• Unused and legacy removal overlap heavily and should be coordinated, not duplicated.
• Comment cleanup should generally come last so it reflects the final code.

Subagent Guidance

When delegating:

• Give each subagent a single lane and a clear scope.
• Ask for evidence, not opinions.
• Keep write scopes disjoint when using worker agents.
• Do not hand off the immediate blocker if the next local step depends on it right away.
• If only six concurrent subagents are available, run six lanes first, wait for one or two to finish, then launch the remaining lanes.
• If two lanes propose conflicting edits, resolve the contract locally before more edits land.

Evidence Standard

A recommendation is high confidence only if it has enough evidence for the lane:

• code search confirms the shape of usage
• tool output supports the finding where relevant
• entry points and runtime registrations were checked
• test or type coverage exists, or a direct validation path exists
• the change simplifies the code without silently broadening behavior

If any of those are missing, keep the recommendation in the report but do not implement it.

Deliverables

For each lane, produce:

1. A critical assessment of the current state.
2. A recommendation list split into high, medium, and low confidence.
3. Implemented high-confidence changes only.
4. A validation summary with commands run and remaining gaps.

Use references/report-template.md as the default reporting format.

Validation

Validate at two levels:

• Local validation after each lane or batch: targeted tests, typechecks, lint, focused runtime checks.
• Final validation after integration: full repo test or the strongest available equivalent.

Do not claim the repo is "clean" if validation was partial. State exactly what was and was not verified.

References

• references/baseline.md: repo setup, inventory, and safety gates
• references/report-template.md: standard output structure
• references/lane-1-dedupe.md
• references/lane-2-shared-types.md
• references/lane-3-unused-code.md
• references/lane-4-circular-deps.md
• references/lane-5-strong-types.md
• references/lane-6-error-handling.md
• references/lane-7-legacy-code.md
• references/lane-8-comment-hygiene.md