reflect

Reflect

Review the conversation and persist learnings - to brain/, to skill files, or as structural enforcement.

Process

Track the review in the active plan when one exists; otherwise use the available planning tools or a short checklist.

1. Scan the conversation for:
   • Mistakes made and corrections received
   • User preferences and workflow patterns
   • Codebase knowledge gained (architecture, gotchas, patterns)
   • Tool/library quirks discovered
   • Decisions made and their rationale
   • Friction in skill execution, orchestration, or delegation
   • Repeated manual steps that could be automated or encoded
2. Identify lessons that will matter in a future session. If none qualify, finish here.
3. Route and persist each remaining learning during this reflection. Before a brain write, read brain/index.md and the relevant topic notes. Write only what those notes do not already cover; keep reusable guidance in indexed topic notes, skill instructions, or structural enforcement. An existing active plan may link to the saved guidance when useful to its task.
4. Reconcile navigation using the brain skill after a brain write. Hooks own the root inventory.

Routing

Not everything belongs in the brain. Route each learning to where it will have the most impact.

Structural enforcement check

Before routing a learning to brain/, ask: can this be a lint rule, script, metadata flag, or runtime check? If yes, encode it structurally and skip the brain note. See brain/principles/encode-lessons-in-structure.md.

Brain files (brain/)

Codebase knowledge, delegation principles, gotchas - anything that informs future sessions. This is the default destination. Activate the brain skill for writing conventions.

• One topic per file. File name = topic slug.
• Group in directories with index files using standard Markdown links.
• No inlined content in index files.

Skill improvements (.agents/skills/<skill>/)

If a learning is about how a specific skill works - its process, prompts, or edge cases - update the skill directly. Activate the create-skill or skill-creator skill when available; otherwise preserve its invocation controls, keep resources self-contained, and verify the affected procedure directly.

Orchestration workflow improvements

If the session revealed systemic orchestration issues, route to:

• Brain principle (new delegation heuristic) → brain/principles/, linked from brain/principles.md
• Skill mechanics change (monitoring loop, review step) → relevant skill file
• New skill opportunity (recurring workflow that could be encoded) → note in summary for the user

Backlog items (brain/todos.md)

Follow-up work that can't be done during reflection - bugs, non-trivial rewrites, tooling gaps. Activate the todo skill to file.

Summary

## Reflect Summary
- Brain: [files created/updated, one-line each]
- Skills: [skill files modified, one-line each]
- Structural: [rules/scripts/checks added]
- Todos: [follow-up items filed]