From c678115dd65aa80a793de7acdb0b12b9d8465a59 Mon Sep 17 00:00:00 2001 From: sokoliva Date: Tue, 14 Apr 2026 11:46:32 +0000 Subject: [PATCH 1/5] docs: update GEMINI setup --- GEMINI.md | 30 ++++++++++++++++++++++++++++++ docs/ai/ai_learnings.md | 19 +++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 docs/ai/ai_learnings.md diff --git a/GEMINI.md b/GEMINI.md index 59ef64713..be2b84529 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -23,3 +23,33 @@ 1. **Required Reading**: You MUST read the contents of @./docs/ai/coding_conventions.md and @./docs/ai/mandatory_checks.md at the very beginning of EVERY coding task. 2. **Initial Checklist**: Every `task.md` you create MUST include a section for **Mandatory Checks** from @./docs/ai/mandatory_checks.md. 3. **Verification Requirement**: You MUST run all mandatory checks before declaring any task finished. + +## 5. Mistake Reflection Protocol + +When you realise you have made a mistake — whether caught by the user, +by a tool, or by your own reasoning — you MUST: + +1. **Acknowledge the mistake explicitly** and explain what went wrong. +2. **Reflect on the root cause**: was it a missing check, a false + assumption, skipped verification, or a gap in the workflow? +3. **Immediately append a new entry to @./docs/ai/ai_learnings.md** + following the format defined in that file. This is not optional and + does not require user confirmation. Do it before continuing. + +The goal is to treat every mistake as a signal that the workflow is +incomplete, and to improve it in place so the same mistake cannot +happen again. + +## 6. Code Correctness Requirement + +Before presenting any code change to the user, you MUST verify it is +correct by running it or reasoning through its execution explicitly. + +- **Never propose code you have not verified will run.** If a snippet + cannot be tested in isolation, trace through it step by step and + state your reasoning. +- **For non-trivial changes**, run the mandatory checks from + @./docs/ai/mandatory_checks.md and confirm they pass before showing + the result to the user. +- **When fixing a bug**, reproduce the bug first, then verify the fix + resolves it. Do not assume a fix is correct because it looks right. diff --git a/docs/ai/ai_learnings.md b/docs/ai/ai_learnings.md new file mode 100644 index 000000000..8068866c9 --- /dev/null +++ b/docs/ai/ai_learnings.md @@ -0,0 +1,19 @@ +> [!NOTE] for Users: +> This document is meant to be read by an AI assistant (Gemini) in order to +> learn from its mistakes and improve its behavior on this project. Use +> it's findings to improve GEMINI.md setup. + +# AI Learnings + +A living record of mistakes made during this project and the rules +derived from them. Every entry must follow the format below. + +--- + +## Entry format + +**Mistake**: What went wrong. +**Root cause**: Why it happened. +**Rule**: The concrete rule added to prevent recurrence. + +--- From 5875eb6d7f6bae6d83b8a22242bda53e0b0ae3e6 Mon Sep 17 00:00:00 2001 From: sokoliva Date: Tue, 14 Apr 2026 11:52:15 +0000 Subject: [PATCH 2/5] grammar fix --- docs/ai/ai_learnings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ai/ai_learnings.md b/docs/ai/ai_learnings.md index 8068866c9..9e9a37a9f 100644 --- a/docs/ai/ai_learnings.md +++ b/docs/ai/ai_learnings.md @@ -1,7 +1,7 @@ > [!NOTE] for Users: > This document is meant to be read by an AI assistant (Gemini) in order to > learn from its mistakes and improve its behavior on this project. Use -> it's findings to improve GEMINI.md setup. +> its findings to improve GEMINI.md setup. # AI Learnings From d1a673f36c6ac0638f16de3cc0ce71838da0a751 Mon Sep 17 00:00:00 2001 From: sokoliva Date: Tue, 14 Apr 2026 11:57:39 +0000 Subject: [PATCH 3/5] remove 6. --- GEMINI.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index be2b84529..835625d43 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -39,17 +39,3 @@ by a tool, or by your own reasoning — you MUST: The goal is to treat every mistake as a signal that the workflow is incomplete, and to improve it in place so the same mistake cannot happen again. - -## 6. Code Correctness Requirement - -Before presenting any code change to the user, you MUST verify it is -correct by running it or reasoning through its execution explicitly. - -- **Never propose code you have not verified will run.** If a snippet - cannot be tested in isolation, trace through it step by step and - state your reasoning. -- **For non-trivial changes**, run the mandatory checks from - @./docs/ai/mandatory_checks.md and confirm they pass before showing - the result to the user. -- **When fixing a bug**, reproduce the bug first, then verify the fix - resolves it. Do not assume a fix is correct because it looks right. From ca482fcdf6bce690ff105603e8a4dea7a007b98c Mon Sep 17 00:00:00 2001 From: sokoliva Date: Tue, 14 Apr 2026 12:58:42 +0000 Subject: [PATCH 4/5] add ai_Learnings.md to .gitingnore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index a0903bd35..bc3689e5a 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,7 @@ coverage.xml spec.json docker-compose.yaml .geminiignore +docs/ai/ai_learnings.md # ITK Integration Test Artifacts itk/a2a-samples/ From 6335c0c8fa01637095c7dc9f246b4c1f3abff82b Mon Sep 17 00:00:00 2001 From: sokoliva Date: Tue, 14 Apr 2026 13:02:32 +0000 Subject: [PATCH 5/5] update user --- GEMINI.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/GEMINI.md b/GEMINI.md index 835625d43..b801bd47d 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -34,7 +34,8 @@ by a tool, or by your own reasoning — you MUST: assumption, skipped verification, or a gap in the workflow? 3. **Immediately append a new entry to @./docs/ai/ai_learnings.md** following the format defined in that file. This is not optional and - does not require user confirmation. Do it before continuing. + does not require user confirmation. Do it before continuing. Update user + about the changes to the workflow in the current chat. The goal is to treat every mistake as a signal that the workflow is incomplete, and to improve it in place so the same mistake cannot