# Mistake Reflection > Use when you discover you made a mistake — caught by the user, by a tool result, by your own re-reading, or by a failed check. Appends a structured entry to docs/ai/ai_learnings.md and re-reads recent entries to avoid repeats. - Skill: `tomevault-io/mistake-reflection` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/mistake-reflection` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/mistake-reflection/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/mistake-reflection --- # Mistake Reflection Implements the mistake-handling step of `AGENTS.md` §"Mandatory workflow". ## When to load this skill Trigger on ANY of these, without waiting for the user to ask: - The user corrects a factual claim, code change, or assumption. - A tool result contradicts something you just stated or did (lint failure, test failure, type-check failure, file not found, command exit non-zero on something you said would succeed). - You re-read a file or doc and realize a prior statement was wrong or unverified. - You realize mid-task that you skipped a required step (e.g. didn't read `docs/ai/coding_conventions.md`, `docs/ai/mandatory_checks.md`, or `docs/ai/evidence_rules.md` at task start). - You stated an inference as a fact without a `file:line` citation and later had to walk it back. If unsure whether something counts: it counts. False positives are cheap; false negatives are how the same mistake recurs. ## Procedure Do these in order. Do NOT defer to the end of the task. 1. **Acknowledge the mistake to the user explicitly** in the current response. One or two sentences. No hedging, no minimization. 2. **Read recent entries** in `docs/ai/ai_learnings.md` (at minimum the last 5 entries, or the whole file if shorter). If the current mistake is a recurrence of an existing rule, say so explicitly and reference the prior entry's date — do not silently duplicate. 3. **Append a new entry** to `docs/ai/ai_learnings.md` using the template below. Append; do not rewrite existing entries. 4. **Continue the original task** only after steps 1–3 are done. ## Entry template Copy this verbatim, fill in each field, append to the end of the file (after the existing `---` separator): ```markdown ## YYYY-MM-DD — - **Mistake**: What went wrong. Be concrete. Quote the wrong claim or describe the wrong action. Include `file:line` references where applicable. - **Trigger**: How the mistake surfaced (user correction, tool output, self-review). Include the specific signal if it was a tool result. - **Root cause**: Why it happened. Distinguish between (a) missing knowledge, (b) skipped verification step, (c) false assumption from pattern-matching, (d) workflow gap. Avoid generic "I didn't think carefully" — name the specific failure mode. - **Recurrence of**: If this matches an existing rule, link to the prior entry's date. Otherwise write "new". - **Rule**: A concrete, checkable rule that would have prevented this. Phrase as an imperative ("Before X, do Y"). If the rule already exists and was violated, the rule should be about *enforcement* (e.g. a check to add to a skill, a step to add to AGENTS.md), not a restatement of the existing rule. ``` ## Anti-patterns to avoid - **Don't restate the same lesson with new wording.** If you'd write essentially the same rule again, the real fix is to make the rule self-enforcing (update a skill or `AGENTS.md`), not to add a third entry. - **Don't let rules go stale.** When you read prior entries, flag stale tooling references and either update them or note the staleness in your new entry. - **Don't write rules that depend on you remembering to follow them.** If a rule is "remember to do X at the start of every task", it will be skipped. Prefer rules that bind to a tool, a skill trigger, or a CI check. - **Don't bury the acknowledgement.** Tell the user up front in the response that you got it wrong, before describing the fix. ## Cleanup ritual Before appending, check the file's length: - **≥ 10 entries**: pause and propose to the user that one or more entries be either (a) deleted (if obsolete or one-off), or (b) promoted into the workflow somewhere it will actually be read. If the candidate rule is about claims/citations/evidence specifically, `docs/ai/evidence_rules.md` is a natural target — otherwise leave the choice of destination to the user. Do this *before* adding the new entry, so the file doesn't grow monotonically and stop being read. This ritual is the only mechanism preventing `ai_learnings.md` from becoming a write-only graveyard. ## Repo-specific notes - `docs/ai/ai_learnings.md` is **gitignored**. Entries are local to the developer's checkout and will not be seen by other agents or in CI. The file is for the human developer to improve `AGENTS.md` / skills based on patterns. - The protocol source and trigger pointer both live in `AGENTS.md` §"Mandatory workflow". `GEMINI.md` is a deprecated stub. - Date format is `YYYY-MM-DD` to match existing entries. --- > Source: [a2aproject/a2a-python](https://github.com/a2aproject/a2a-python) — distributed by [TomeVault](https://tomevault.io).