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):

## YYYY-MM-DD — <one-line summary>

- **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.