| name | ctx-reflect |
| description | Reflect on session progress. Use at natural breakpoints, after unexpected behavior, or when shifting to a different task. |
Pause and reflect on this session. Review what has been
accomplished and identify context worth persisting.
When to Use
- At natural breakpoints (feature complete, bug fixed, task
done)
- After unexpected behavior or a debugging detour
- When shifting from one task to a different one
- When context is getting full and the session may end soon
- When the user explicitly asks to reflect or wrap up
When NOT to Use
- At the very start of a session (nothing to reflect on yet)
- After trivial changes (a typo fix does not need reflection)
- When the user is in flow and has not paused; do not interrupt
with unsolicited reflection
Usage Examples
/ctx-reflect
/ctx-reflect (after fixing the auth bug)
Reflection Checklist
Before listing items, step back and reason through the session
as a whole: what was the arc, what surprised you, what would
you do differently? This framing surfaces insights that a
mechanical checklist misses.
Work through each category. Skip categories with nothing
to report; do not force empty sections.
1. Learnings
- Did we discover any gotchas, bugs, or unexpected behavior?
- Did we learn something about the codebase, tools, or
patterns?
- Would this help a future session avoid problems?
- Is it specific to this project? (General knowledge does not
belong in LEARNINGS.md)
2. Decisions
- Did we make any architectural or design choices?
- Did we choose between alternatives? What was the trade-off?
- Should the rationale be captured for future sessions?
3. Tasks
- Did we complete any tasks? (Mark done in TASKS.md)
- Did we start any tasks that are not yet finished?
- Should new tasks be added for follow-up work discovered
during this session?
4. Session Notes
- Was this a significant session worth a full snapshot?
- Would a future session benefit from the discussion context?
- Are there open threads that a future session needs to pick
up?
Output Format
After reflecting, provide:
- Summary: what was accomplished (2-3 sentences)
- Suggested persists: list what should be saved, with
the specific command or file for each item
- Offer: ask the user which items to persist
Good Example
This session implemented the cooldown mechanism for
ctx agent and updated all related docs. We discovered
that $PPID in hook context resolves to the Claude Code
process PID, which is unique per session.
I'd suggest persisting:
- Learning:
$PPID in PreToolUse hooks resolves to
the Claude Code PID (unique per session)
ctx learning add "Title" --session-id ID --branch BR --commit HASH --context "..." --lesson "..." --application "..."
- Task: mark "Add cooldown to ctx agent" as done
- Decision: tombstone-based cooldown with 10m default
ctx decision add "Title" --session-id ID --branch BR --commit HASH --context "..." --rationale "..." --consequence "..."
Want me to persist any of these?
Bad Examples
- "We did some stuff. Want me to save it?" (too vague;
no specific items or commands)
- Listing 10 trivial learnings that are general knowledge
(only project-specific insights belong)
- Persisting without asking (always get user confirmation)
Persistence Commands
| What to persist | Command |
|---|
| Learning | ctx learning add "Title" --session-id ID --branch BR --commit HASH --context "..." --lesson "..." --application "..." |
| Decision | ctx decision add "Title" --session-id ID --branch BR --commit HASH --context "..." --rationale "..." --consequence "..." |
| Task completed | Edit TASKS.md directly |
| New task | ctx task add "Description" --session-id ID --branch BR --commit HASH |
Quality Checklist
Before presenting the reflection, verify:
