🦆 debug_duck #

A professional debugging assistant with zero coding skills and strong opinions.

debug_duck brings the legendary Rubber Duck Debugging methodology to Flutter — with humor, structured logging, and verified utility.

✨ Why debug_duck? #

We've all been there. You stare at the code. The code stares back. You say, "This should work." The console says, "Null check operator used on a null value."

debug_duck forces you to slow down, explain your logic, and spot your own silly mistakes before they become permanent residents in your codebase.

It doesn't fix your code. It makes YOU fix your code.

🚀 Key Features #

� Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  debug_duck: ^0.0.1

Or run:

flutter pub add debug_duck

� Usage #

1. Wrap Your App (Optional Overlay) #

To see the floating duck, wrap your main app widget:

import 'package:debug_duck/debug_duck.dart';

void main() {
  runApp(
    DebugDuck(
      child: MyApp(), // 👈 Wrap it here
    ),
  );
}

2. Start a Debugging Session #

When you're stuck, start a session to track your meaningful thoughts (and despair).

// Start tracking
DebugDuck.startSession();

// Log your assumptions
DebugDuck.note("User should be logged in here");
DebugDuck.note("API response: ${response.statusCode}");

// End and review
DebugDuck.endSession();

3. The "Explain It Slowly" Protocol #

Stuck on a logic error? Force yourself to stop clicking random things.

DebugDuck.explain(); 
// Pauses and prompts: "Say it. Out loud. Slowly."

⚙️ Configuration #

Customize the duck's personality in your main():

void main() {
  DebugDuck.configure(DebugDuckConfig(
    enabled: true,         // Master switch
    showOverlay: true,     // Show the floating duck
    roastLevel: DuckRoastLevel.sarcastic, // polite, sarcastic, or savage
    logSessions: true,     // Enable session recording
  ));

  runApp(const MyApp());
}

Roast Levels #

• Polite: Gentle nudges. "Are you sure?"
• Sarcastic: The default experience. "That rebuild was unnecessary."
• Savage: Emotional damage. Use at your own risk.

🛡️ Zero Production Impact #

We take performance seriously.

• Tree Shaking: All DebugDuck methods verify kDebugMode.
• Compiler Optimization: most calls are optimized away in release builds.
• No Assets: No heavy assets are bundled in your final app.

� Contributing #

Found a bug? Have a roast to add?

1. Fork the repo.
2. Add your feature (or roast).
3. Submit a PR.

📄 License #

MIT License. Use it, fork it, roast it.

Built with 💙 and 🦆 by Maher-Tec