feat(session-flow): add a since-your-last-message catch-up scope to /session-flow:orient #8640

Refs: #7575

Agent Brief

Type: Feature
Summary: /session-flow:orient gains a catch-up scope that answers "what happened since my last message, and what needs me": "Needs you" first, one short item per decision only the user can make, a live re-check of everything the chat touched, under a word cap the user can set.

Current behavior:

• Orient gives a four-part briefing (goal, where we stand, decisions, direction) over the whole session and durable state (plugins/session-flow/skills/orient/SKILL.md:58-76). It reports off-thread work "at a glance" and never re-checks it (SKILL.md:51-56).
• It has no anchor at the user's last message, no list of what needs the user, and no length limit. plugins/session-flow/.claude-plugin/plugin.json has no orient setting.

Desired behavior:

• A catch-up scope, chosen with the argument catch-up (the existing description trigger "catch me up" already routes here; do not edit the description):
  • Anchor: the user's last message they wrote themselves. Notifications and subagent results are not the user's messages. Assume the user remembers that message and nothing after it.
  • Gather, read-only: the session's own work since the anchor, subagent reports, and messages from others in the chat. Re-check the current state of each pull request, CI run and agent the chat touched; say which are still running and which could not be checked. Change nothing to gather.
  • Action items: a decision or step only the user can take (a product choice, an approval, an irreversible action, access the session lacks), including any still waiting from before the anchor. Work the session can still do itself is not an action item.
  • Order of the reply: first a "Needs you" section that opens with the number of action items, or says there are none and stops when nothing happened. Then what happened, most important first, each result with what it means for the user; skip steps that changed nothing; one line for work left the session can do. Then each action item: the decision, why it matters now, the options and what each costs, the recommendation, what happens if the user does not answer, and any part not known, said as unknown.
  • Name each pull request, branch or agent as the user would know it.
  • A visual (table, diagram) only when one exists or can be built from what is in hand; never invent a number or picture.
  • The whole reply stays within the word cap, visuals excluded.
• New userConfig key in plugin.json, orient_catch_up_word_cap, type number, default 250, minimum 150; the skill reads it as ${user_config.orient_catch_up_word_cap} (unexpanded or empty means 250).
• The four-part briefing stays the default scope; no existing sentence is removed.
• Two eval cases in evals/evals.json: (a) a catch-up after subagent results and two pending decisions opens with "2" action items, each with a recommendation and an if-unanswered line; (b) a catch-up where nothing happened and nothing waits says so and stops.

Key interfaces:

• /session-flow:orient catch-up.
• userConfig.orient_catch_up_word_cap (default 250).

Clarifications

Known call, 2026-10-20. Each open point and its answer:

• Manifest key for the minimum. The bound key is min, not minimum. userConfig options are strict objects, "An unknown key fails validation", and the bounds row reads "min / max | No | Bounds for number" (https://code.claude.com/docs/en/plugins-reference#user-configuration). type, title and description are required. Copy the shape of observer_poll_seconds in plugins/session-flow/.claude-plugin/plugin.json:72-78 ("type": "number", "default": 5, "min": 1). The acceptance line below now says "min": 150.
• Substitution in the skill body. ${user_config.KEY} is "substituted in ... skill and agent content" for non-sensitive values (https://code.claude.com/docs/en/plugins-reference#reference-a-saved-value). The docs do not say what an unset key leaves behind, so follow the repo's wording in plugins/session-flow/skills/audit-sessions/SKILL.md:82-85: an unexpanded ${user_config.…} or an empty value means the default (250). A value below 150 is treated as 150 (judgment).
• When the scope runs. Only on the explicit argument catch-up. A bare "catch me up" keeps the four-part briefing, because the existing eval case 1 (plugins/session-flow/skills/orient/evals/evals.json:7, prompt "Where were we? Catch me up on this session.") expects the briefing and must keep passing.
• Argument hint. Orient's frontmatter has no argument-hint (plugins/session-flow/skills/orient/SKILL.md:1-5). Add argument-hint: "[catch-up]". This adds a line, deletes none, and does not touch the description.
• Eval shape. The file exists with four cases, ids 1-4, each with keys id, name, prompt, expected_output, files ([]), expectations. Add cases (a) and (b) as ids 5 and 6 in that shape.
• Fragment source. A fragment's front matter may hold only bump: (scripts/lib/changelog-fragments.sh:142), so the source goes in the body under ### Added as a link to the pinned upstream skill, https://github.com/cursor/plugins/tree/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/ketchup (docs/upstream/cursor-pstack.md:110). Create it with scripts/new-changelog-fragment.sh session-flow minor.
• Other docs. Nothing else lists userConfig keys for this plugin (plugins/session-flow/skills/setup/SKILL.md:50-57 lists only the observer keys), so no other file changes.

Acceptance criteria:

• The diff to plugins/session-flow/skills/orient/SKILL.md adds the catch-up scope with the anchor, gather, action-item and reply-order rules above, and deletes no line.
• plugin.json gains orient_catch_up_word_cap with "type": "number", "default": 250 and "min": 150 (read from the diff).
• plugins/skill-quality/scripts/check-evals-quality.sh plugins/session-flow/skills/orient/evals/evals.json exits 0, and the set holds cases (a) and (b) asserting the behavior named.
• scripts/check-changelog-fragments.sh --check passes, with one minor fragment for session-flow that names pstack ketchup as the source.
• CI's check-skills and check-plugins pass on the PR (PR checks; this run does not run them).

Out of scope:

• orient all, which rolls up lanes on one machine by default, and live sessions waiting on the owner: how orient enumerates other live sessions is not yet decided (D87, Q123).
• A configurable visual setting (D67 says optional and configurable; no key or default is recorded).
• The morning brief and its "Landed" section (work-items).
• The docs/upstream/cursor-pstack.md ketchup row (docs(upstream): re-audit the pstack record past cursor/plugins 99743e9c15 and re-pin it #8542 re-audits that record).

Origin:

• Catch-up scope from ketchup, anchor at the user's own last message, "Needs you" first, per-item decision, why now, options, recommendation, if unanswered, unknowns, live re-check: Lauren's (ketchup), D67.
• Ketchup's current item shape and order; word cap a setting, default 250, 150 available: Q562.
• Declined: ketchup's name, persona voice and mandatory visual: owner, D67.

Do not run with: #8642 (orchestrate coordinator; both add a session-flow fragment and edit session-flow skills; different files, so only a merge-order note). #8538 edits retro; no shared file.

Slice of #7575, drafted by the poteto-review session from the thread's recorded decisions.