Tutorial: repairing RTL with AI assistance

Have Nelix Agent diagnose a failed simulation, see its repair verified, and decide whether to accept it.

StudentEngineer 2 min read · Updated 2026-10-24

        On this page
        ObjectiveBefore you start1. Ask for a diagnosis2. Read it critically3. The repair is verified before you decide4. Accept, or do not5. ConfirmIf you change your mindHow to tell it workedCommon problemsNext
      

Objective#

Use Nelix Agent on a failed simulation, and understand each step between a proposal and a change to your file.

Before you start#

A project with a failing simulation. The second guided project, g2-debug, fails on purpose and is ideal.
Some Nelix Agent allowance left. The AI meter in the top bar shows it.

nelix new g2-debug --template g2-debug
cd ~/project/g2-debug
nelix test

Note the run id the test prints, such as TST-20261005-0003.

1. Ask for a diagnosis#

On Overview, the failed Simulate card has Debug with Nelix Agent. Or in the terminal:

nelix debug

With no id it uses your latest failed test. To name one: nelix debug TST-20261005-0003.

Expected: a diagnosis that names what failed, the evidence, and a proposed change to rtl/top.sv.

2. Read it critically#

Check three things before going further.

Check	Why
Does the evidence match what you see in the waveform?	The diagnosis must rest on the run, not on a guess
Does the proposed change touch only the design?	A repair must not rewrite the test
Can you explain why the change fixes it?	If you cannot, do not accept it yet

3. The repair is verified before you decide#

The lab applies the proposed change to a separate copy of your project and runs your test there. You can accept it only after it passes there. Your working files have not changed.

From the terminal, the same steps are explicit:

Step	Command
Propose a repair	`nelix repair propose`
Review it	`nelix repair show ID`
Approve it for verification	`nelix repair approve ID --approve`
Verify it in a separate copy	`nelix repair verify ID`
Accept the verified repair	`nelix repair accept ID --approve`
Merge it into your working RTL	`nelix repair merge ID --approve`

4. Accept, or do not#

Accepting does not change your file yet. Merge writes the change into rtl/top.sv, keeps a backup and runs your test again. If you would rather write the fix yourself, discard it:

nelix repair discard ID

5. Confirm#

nelix test

Expected: PASS=1 FAIL=0, on a new run id. That run, on your changed file, is the proof.

If you change your mind#

nelix repair rollback ID --approve

restores the RTL from before the merge.

How to tell it worked#

A new simulation passes, and you understand the change that made it pass.

Common problems#

Problem	Meaning
Nelix Agent is not available	`nelix ai status` shows why. The three stages still work
Your AI allowance is used up	Nelix Agent pauses until it renews (the AI meter shows when). Debug by hand, as in the previous tutorial
The repair did not verify	The proposed change did not make the test pass. `nelix repair revise ID` shows why; to get a new fix, press Debug with Nelix Agent again or run `nelix repair propose`
Your file changed since the failed run	The repair was made for the older version. Run the test again and start from the new failure

Next#

Do the same bug by hand, if you have not: Debugging a failed simulation. Comparing your reasoning with the AI's is the fastest way to learn to judge it.

Diagnosis, proposed patches and verificationHow Nelix Agent finds the cause of a failure, and why a repair is tested before you can accept it.
Tutorial: debugging a failed simulationUse the failure message and the waveform to find one bug, with the second guided project.

Something unclear or missing? Send feedbackSign in and use Feedback to tell us.