danmestas reflect
A structured post-task critique. Inspired by the Reflexion pattern: the agent reasons over its own recent transcript and emits a written self-assessment with specific, actionable proposals. The output is reviewable; nothing auto-applies.
When to invoke
- User explicit:
/reflect, "let's retro this", "what went wrong", "critique that". - Auto-firing: after a "meaningful task" ships. The agent decides what "meaningful" means — typical heuristics:
- A PR was opened or merged.
- A multi-step plan executed to completion.
- A reported bug was fixed and verified.
- A new skill, hook, or component landed.
- Skip for trivial single-tool tasks (one read, one edit, one shell command). Reflection on noise is noise.
Mode hint
Accepts --mode <name> (or mode: in the task frontmatter) to bias the
critique toward a specific domain. The mode value is a hint for the agent:
look up modes/<name>/ and weight the critique sections
toward that domain's observation_types and memory_topics. Examples:
--mode code— emphasize architecture, performance, refactor opportunities, test patterns.--mode design— emphasize affordances, feedback, mapping, accessibility.--mode ops— emphasize incident retrospection, alerting, runbook gaps, permission hygiene.
When no mode is set, run a balanced critique across all categories.
The structured critique
Produce a markdown report with exactly these five sections, in order:
1. Summary
One sentence describing what was attempted.
Built 7 Evolution-category skills under
skills/<name>/SKILL.mdand opened PR #N.
2. What went well
A bullet list of 2-5 items. Be specific — "tests passed" is too generic; "validate caught a bad category enum on the second skill before commit" is useful.
3. What didn't
A bullet list of 2-5 items. Cite the moment things went off-track:
- Quote the exact tool error or user correction.
- Identify the upstream cause (wrong assumption, missing context, skipped check).
- Note whether you noticed it yourself or the user pointed it out (the latter is worse).
4. Specific actionable proposals
For each "didn't go well" item, propose ONE concrete change. Each proposal must name:
- The artifact to change: a file path, a memory entry, a skill description, a settings.json key.
- The diff shape: what to add, remove, or replace. Quote enough surrounding context to be unambiguous.
- The trigger condition: when next time this proposal would have helped.
Example:
Proposal: add
npm run validateto the pre-commit allowlist in.claude/settings.jsonso future commits in this repo don't trigger a permission prompt for it.Trigger condition: any commit in
agent-config. Saw this 3× this session.
5. Open questions
Things the agent isn't sure about. Phrase as questions for the human, not as more proposals. ("Should reflection auto-fire on PR-merged events, or wait for explicit /reflect?")
Output
~/.claude/evolution-reports/<project>/reflections/<YYYY-MM-DD>-<topic-slug>.md
<topic-slug> is a short kebab-case description of the task, ≤4 words, derived from the conversation. E.g., 2026-04-27-evolution-skills.md.
After writing, print the path to the user. Do not pre-apply any of the proposals.
Pairing with /memorize
If the user agrees with proposals from this reflection, the memorize skill (auto-fired on agreement, or invoked by the user) converts the relevant proposals into durable ADRs or memory entries.
Anti-patterns
- No bland self-praise. "We did a good job" with no specifics is wasted output.
- No rumination. Cap each section at 5 bullets. Long reflections don't get read.
- No auto-apply. Even obvious-looking proposals stay as proposals. The human reviews and triggers
/memorizefor the ones worth keeping. - No vague proposals. "Improve error handling" fails the spec. "Wrap the Bash call at file:line in a try/catch and log to " passes.
See also
skills/memorize/SKILL.md— converts agreed proposals into durable ADRs/memory.skills/evolution-engine/SKILL.md— does pattern-detection across sessions; reflection is per-task.skills/skill-gap-detector/SKILL.md— finds missing skills; reflection finds tactical fixes.