The Self-Healing Robot Helper (explained to a 10 years old kid)

This is a friendly guide to our project. It is not part of the code and is just here to help anyone understand what I built. Think of it as a storybook version of the project.

---

1. The big idea in one sentence

We built a robot helper that watches our computer project, and when something breaks, the robot fixes it by itself — kind of like a video game character that heals its own health bar.

---

2. Let's start with a story

Imagine you build a tower out of LEGO bricks. Every time you add a new brick, you check three things:

1. Are the bricks neat and lined up? (tidy)

2. Does the tower still stand up? (works)

3. Is it safe to show your friends? (ready)

Now imagine you had a tiny helper robot sitting next to the tower. Every time you add a brick, the robot checks those three things super fast. If something is wrong — say a brick is crooked — the robot fixes the crooked brick for you and leaves you a note saying "I fixed it!"

That helper robot is our project. The LEGO tower is a small computer program, and the robot is the "self-healing pipeline."

---

3. What are the pieces?

Our project has a few parts. Here they are with simple names:

The toy app (app/)

A tiny program that does math, like a calculator. It can add, subtract, multiply, and divide. This is our "LEGO tower" — the thing we are building.

The tests (tests/)

These are like a checklist of questions that make sure the calculator is correct. For example: "Does 2 + 3 equal 5?" If the calculator gives the wrong answer, a test says "NOPE, that's wrong!" and raises its hand.

The pipeline (.gitlab-ci.yml)

This is the conveyor belt in a factory. Every time we change the program, it rides along the belt and passes through four stations:

1. Verify — "Is it tidy and correct?" (checks style + runs the tests)

2. Package — "Can we box it up?" (makes sure it builds)

3. Release — "Does it turn on?" (starts the app and says hello to it)

4. Heal — the special station that only wakes up if something broke

The robot's brain (automation/)

Two small helpers:

• diagnose.py — the robot's detective. It reads what went wrong and figures out what kind of problem it is (messy code? a missing piece? a math mistake?).

• heal.py — the robot's fix-it hands. Depending on the problem, it either fixes it right away or calls a smarter helper (see below).

---

4. How does the healing actually work?

When the conveyor belt finds a problem, the Heal station wakes up. The detective (diagnose.py) looks at the mess and sorts the problem into one of a few buckets:

Kind of problem	What it means (kid version)	Who fixes it
Messy code	Toys left on the floor	The robot tidies it up itself
Missing piece	A LEGO brick is missing from the box	The robot adds the missing brick
Math mistake	The calculator says 2 + 2 = 5	A super-smart AI helper fixes it
Broken build	The instructions have a typo	The super-smart AI helper fixes it

The two kinds of fixing

1. Easy fixes — the robot does them alone. Some problems are simple, like tidying up messy code or adding a missing piece. The robot can do these all by itself. It fixes the problem, then leaves a note (called a "merge request") that says "Here's my fix, want to use it?"

2. Tricky fixes — the robot calls a smarter friend. Some problems need real thinking, like fixing a math mistake in the program. That's too hard for our little robot's simple rules. So it calls a smarter friend named GitLab Duo — an AI that can read the code, understand the mistake, and write the correct fix. Our robot is honest: instead of pretending it can fix everything, it says "This one needs the smart friend," and hands it over.

Think of it like homework: easy questions you answer yourself, but for the really tricky one you ask a clever teacher for help.

---

5. The rule book for the smart friend (AGENTS.md)

When our robot asks the smart AI friend (GitLab Duo) for help, it gives the friend a rule book so the friend behaves well. The most important rules:

• Fix the program, never change the checklist. (You can't pass a test by erasing the questions!)

• Don't break the conveyor belt to make things look okay.

• Make the smallest fix possible. Don't rebuild the whole tower to fix one brick.

• If you're not sure, ask a grown-up (a human) instead of guessing.

---

6. What does "self-healing" really mean here?

It means: you make a change, and if you accidentally break something, you don't have to fix it by hand. The pipeline notices the break, figures out what's wrong, and fixes it (or asks the AI to fix it). You could walk away, come back later, and find it already healed. That's the magic.

---

7. A quick example from start to finish

1. We change the calculator, but oops — we make add do subtraction by mistake. Now 2 + 3 gives 5... minus... it gives the wrong answer.

2. The conveyor belt runs. The Verify station's checklist shouts: "2 + 3 should be 5, but it's -1! FAIL!"

3. The Heal station wakes up. The detective says: "This is a math mistake (a test failure)."

4. Our robot knows math mistakes need real thinking, so it hands the problem to the smart AI friend, GitLab Duo.

5. Duo reads the code, understands the mistake, and writes the correct fix: add should add, not subtract.

6. The fix gets checked again, passes, and the tower is healthy once more. 🎉

---

8. Why is this cool / why did we build it?

There's a big coding contest (a "hackathon") with a theme: "Code generation is solved — what happens next?" The idea is that computers are already good at writing code, so the next challenge is making computers good at taking care of code after it's written — testing it, checking it, and fixing it.

Our project is one answer: a pipeline that heals itself. Less boring cleanup for humans, more time for the fun, creative parts.

---

9. The whole thing as one picture

   You change the program
            |
            v
   +---------------------------+
   |  Conveyor belt (pipeline) |
   |  Verify -> Package ->     |
   |  Release                  |
   +------------+--------------+
      all good? |  something broke?
         |      |
       done     v
          +------------------------+
          |  Heal station          |
          |  Detective figures     |
          |  out the problem       |
          +----+--------------+----+
         easy  |              |  tricky
               v              v
      Robot fixes it    Ask smart AI friend
      and leaves a      (GitLab Duo) to
      note              write the fix

---

10. Super-short version (if you only read one thing)

We made a computer project that fixes itself when it breaks. Easy problems, a little robot handles. Hard problems, a smart AI friend handles. Either way, you barely have to lift a finger. That's the self-healing pipeline. 🤖💛