session-end

name	session-end
description	End-of-session cleanup, documentation, and commit
disable-model-invocation	true

/session-end [summary]

End-of-session cleanup, documentation, and commit.

Steps

1. Reflect on what could have gone smoother. Before writing anything, ask the user what they noticed. Surface your own observations too: what was slow, what was a false start, where the control loop broke, what worked well. This conversation produces the learnings that feed into the session notes, the investigation log, and the routing step. Don't skip this even when a session feels clean — the smoothest sessions still have calibration signals.

1a. Fix class audit. If the session included fixes (code, documentation, process, plays, tooling), enumerate each fix and ask: is this a narrow instance of a broader class of the same issue? Would it be reasonable for the user to discover the class unaddressed and say "wait, I thought we fixed this"? For each fix, check for the same pattern in sibling locations (other sort keys in the same file, other plays in the same doc, other tools with the same interface shape). If the class is broader than what was fixed, present to the user for their preference on whether to fix it now or log it explicitly as a known gap.

2. Read Monitor summary (if Monitor was active):
   • Check for [MONITOR SESSION SUMMARY] in recent context, or read from ~/.agenterminal/monitor-summaries/
   • Note any findings that diverge from your own assessment of the session
   • Incorporate or explicitly disagree with Monitor observations when drafting session notes in the next step

⚠ NARRATION GATE (steps 3-9). The steps below are sequential tool calls that activate going-dark and batch momentum. Before EACH step: say one sentence to the user about what you are doing. Do not make a tool call as your first action after a user message. This has failed: 2026-04-15, 17+ user messages unacknowledged across all of steps 3-9. The plan feeling clear is exactly when narration drops.

3. Write session notes to box/sessions/. File name: YYYY-MM-DD_SHORTID.md where SHORTID is the first 8 characters after session_ in $AGENTERMINAL_SESSION_ID (e.g., 2026-04-01_c15c8b0f.md). Include: goal, what was done, key decisions, and session learnings (from the reflection above). Each session writes its own file — concurrent sessions don't clobber each other. To read last session's notes, find the most recent file: ls -t box/sessions/*.md | head -1.

   Carried-forward items go to GitHub Issues, not session.md. Create new Issues with the carried-forward label using the repo's issue template. Update existing Issues if their state changed. Close Issues that were completed. Items that didn't change don't get touched — that's the structural advantage over the old system.

4. Write to the investigation log via the CLI. First, check for /tmp/ff-{session_id}-failed-commands.log — if it exists, include its full contents in the log entry. This is the mechanical record of every failed command in the session. Then write observations: what was slow, what was manual, what was repeated, what worked well, what almost didn't happen, data source quirks.

   Wasted-turn accounting. The failed-commands.log now includes a reason field (flag_guess, schema_guess, format_guess, gate_block, tool_error, unknown). Review the reasons and count by category. Then add judgment-based wasted turns that no hook catches: self-authorization (manufactured consent), wrong approach (command succeeded but was the wrong path), silent failure (repeated ineffective queries without changing strategy), redundant work (re-reading or re-investigating known ground). Include both mechanical and judgment-based counts in the log entry.

   python3 box/log-cli.py write \
       --date YYYY-MM-DD \
       --topic "Topic here" \
       --lesson "One-line lesson for index" \
       --disposition needs_intervention \
       --bullet "Bold observation." "Detail text explaining the observation." \
       --bullet "Another observation." "More detail."
   

   To search: python3 box/log-cli.py query "keyword" or --date, --topic, --recent N.

5. File observations to feedforward-infra. For each behavioral pattern, tooling friction, or gate failure observed during the session, whether surfaced by the user, the Monitor, failed-command review, or your own review of the session, first search open issues in paulyokota/feedforward-infra for related topics before creating anything new.

   • Run multiple searches against open issues before creating a new issue. At minimum, search once by surface (script/module/gate/play name) and once by the behavior or problem phrase.
   • If those searches are too narrow, too noisy, or inconclusive, keep searching with adjacent terms before deciding the topic is new.
   • Read any plausible matches before deciding they do not cover the topic: gh issue view <number> --repo paulyokota/feedforward-infra
   • If an open issue already covers the topic, add the new session's observation as a comment with gh issue comment <number> --repo paulyokota/feedforward-infra instead of creating a duplicate issue.
   • Only create a new issue when no existing open issue covers the topic.

   Whether commenting or creating, include the raw observation, the turns where it happened, and any relevant context (script name, args, error output). Don't diagnose root causes or design fixes; that's infra's job in a fresh context window with full context budget.

   New issue example:

   gh issue create --repo paulyokota/feedforward-infra \
       --title "Observation: <what happened>" \
       --body "## What happened
   <description>
   
   ## What was expected
   <expected behavior>
   
   ## Context
   - Session: $AGENTERMINAL_SESSION_ID
   - Script/module: <if applicable>
   - Turns: <turn numbers where it happened>"
   

   Skip this step only if no behavioral incidents, tooling friction, or gate failures were surfaced by the user, the Monitor, failed-command review, or your own review of the session.

6. Route learnings to the right file. Investigation judgment learnings are routed by type:

   Learning type	Where it goes	Example
   New investigation principle	MEMORY.md (Investigation Approach section)	"Describe observable behavior, not inferred cause"
   Instance of known principle	Investigation log only	"SC-399: grep match ≠ verification (proxy trust)"
   Event/data fact (event name, property, behavior)	box/posthog-events.md or box/queries.md	"Schedule post event has a source property"
   Card formatting lesson	MEMORY.md Card Formatting — principle only, not card-specific example	"Don't drop ideas from the original card"
   Product fact (feature state, scope, vocabulary)	.claude/rules/product-knowledge.md	"SmartPin v2 is behind feature flag, not GA"

   Behavioral patterns, tooling gotchas, process/safety properties, framework observations, play checklist items, and delegation patterns are infra's domain. File these as GitHub issues in paulyokota/feedforward-infra (step 5) rather than routing to reference/ files or play docs directly.

   MEMORY.md is for investigation judgment, not behavioral interventions. Before adding a learning to MEMORY.md, check whether it's about how to investigate (keep) or how the tooling should work (file to infra). MEMORY.md principles are about evidence evaluation, framing, data source usage — not about process safety.

   After writing, run wc -l on MEMORY.md and state the exact number. If over 170 lines: (a) review for items that belong in topic files instead of MEMORY.md, and (b) look for line-level condensing opportunities. 170 is the action threshold, not 200. Do not do the arithmetic in your head — read the number from wc -l output.

   Remove anything in MEMORY.md that turned out to be wrong.

7. Verify play routing. Confirm that any new or renamed skills are listed in box/plays.md. The routing table points to skill names (not line numbers), so it only needs updating when skills are added, removed, or renamed.

8. Delete session temp directory. Session artifacts are in /tmp/ff-$AGENTERMINAL_SESSION_ID/. Only clean up YOUR session's directory:

   ls /tmp/ff-$AGENTERMINAL_SESSION_ID/ 2>/dev/null && rm -r /tmp/ff-$AGENTERMINAL_SESSION_ID || echo "No session temp directory"
   

   Also clean up the session-scoped CLI verified file:

   rm -f /tmp/ff-cli-verified-$AGENTERMINAL_SESSION_ID.txt
   

   Note: The developer-kit plugin's validate_bash_command.sh hook blocks rm -rf /tmp/... because it pattern-matches rm -rf / as dangerous. Use rm -r (without -f) and check existence first to avoid the block.

   Do NOT use wildcard cleanup (rm -r /tmp/ff-*) — other sessions may be running concurrently.

9. Stage and commit. Stage changed files (box/sessions/*.md, memory files, any other changes). Commit with a descriptive message.

What NOT to do

• Don't push. Pushing creates pressure to skip review.
• Don't update docs/session/last-session.md. That file gets overwritten by the Developer Kit Stop hook.
• Don't update docs/status.md. Duplicative with session notes in box/sessions/.