KB Reflect
Use after failures, user corrections, review findings, repeated tool mistakes, or context misses.
Start from _agent/problem-signals/ or projects/<project>/proposed-changes/problem-reflections/
when automatic hooks or kb_problem.py record captured evidence.
AgentKB keeps Markdown as the canonical storage format. Load the smallest sufficient context first, and make every write reviewable with Git diff.
Context Order
- Read the project
context-pack.md.
- Read
_system/write-policy.md.
- Read relevant problem signals, reflection drafts, task logs, and open questions.
- Read only the notes needed to understand the failure.
Do not read personal/ or archive/ unless the user explicitly authorizes it.
Reflection Record
Capture these fields when turning an incident into durable knowledge:
- Incident: What failed, where, and what evidence proves it.
- Root Cause: The missing assumption, context, rule, guard, or validation.
- Generalized Lesson: The reusable rule that applies beyond this incident.
- Prevention Mechanism: The concrete enforcement surface, such as a test,
lint, runtime guard, eval case, AGENTS proposed change, playbook, skill
update, or context-pack refresh.
- Validation: The command, review, or runtime check that proves the
mechanism works.
- Residual Risk: What remains unfixed and where follow-up should happen.
Procedure
- Describe what failed and why in a concise log entry.
- Identify whether the issue is a one-time mistake, repeated pattern, missing context, unclear rule, or missing validation.
- Extract a generalized lesson without overfitting to a single command, file,
or person.
- Choose a prevention mechanism. Prefer executable checks or workflow gates
when the lesson can be enforced mechanically.
- Decide whether to update a log,
open-questions.md, a playbook,
AGENTS.md proposed change, eval case, test, guard, skill, or context-pack.
- Keep low-confidence reflections in
proposed-changes/.
- If a personal/work lesson may help a project, put the sanitized extract in
projects/<project>/candidates/.
- Review the Git diff.
Promotion Rule
One incident goes to a log or reflection. Repeated, stable lessons can be
promoted by kb-promote.
Do not treat knowledge-base prose as the only fix when the issue can recur in
execution. Pair the reflection with a prevention mechanism or record why that
mechanism is intentionally deferred.
1---2name: kb-reflect3description: Use when failures, corrections, or review findings should become AgentKB knowledge.4---56# KB Reflect78Use after failures, user corrections, review findings, repeated tool mistakes, or context misses.9Start from `_agent/problem-signals/` or `projects/<project>/proposed-changes/problem-reflections/`10when automatic hooks or `kb_problem.py record` captured evidence.1112AgentKB keeps Markdown as the canonical storage format. Load the smallest sufficient context first, and make every write reviewable with Git diff.1314## Context Order15161. Read the project `context-pack.md`.172. Read `_system/write-policy.md`.183. Read relevant problem signals, reflection drafts, task logs, and open questions.194. Read only the notes needed to understand the failure.2021Do not read `personal/` or `archive/` unless the user explicitly authorizes it.2223## Reflection Record2425Capture these fields when turning an incident into durable knowledge:2627- **Incident:** What failed, where, and what evidence proves it.28- **Root Cause:** The missing assumption, context, rule, guard, or validation.29- **Generalized Lesson:** The reusable rule that applies beyond this incident.30- **Prevention Mechanism:** The concrete enforcement surface, such as a test,31 lint, runtime guard, eval case, AGENTS proposed change, playbook, skill32 update, or context-pack refresh.33- **Validation:** The command, review, or runtime check that proves the34 mechanism works.35- **Residual Risk:** What remains unfixed and where follow-up should happen.3637## Procedure38391. Describe what failed and why in a concise log entry.402. Identify whether the issue is a one-time mistake, repeated pattern, missing context, unclear rule, or missing validation.413. Extract a generalized lesson without overfitting to a single command, file,42 or person.434. Choose a prevention mechanism. Prefer executable checks or workflow gates44 when the lesson can be enforced mechanically.455. Decide whether to update a log, `open-questions.md`, a playbook,46 `AGENTS.md` proposed change, eval case, test, guard, skill, or context-pack.476. Keep low-confidence reflections in `proposed-changes/`.487. If a personal/work lesson may help a project, put the sanitized extract in `projects/<project>/candidates/`.498. Review the Git diff.5051## Promotion Rule5253One incident goes to a log or reflection. Repeated, stable lessons can be54promoted by `kb-promote`.5556Do not treat knowledge-base prose as the only fix when the issue can recur in57execution. Pair the reflection with a prevention mechanism or record why that58mechanism is intentionally deferred.
cYz26