#143 docs: correct two assumptions a live experiment falsified

Summary

Docs only. A live experiment on /branch (issue #142) falsified two statements in docs/session-finding-plan.md, and both were load-bearing for how pins and the session list were designed.

Where	Said	Actually
§6, C3 row	"Essentially defunct … no generation chains exist; only meaningful if --fork-session / copy-fork become common"	/branch creates a chain on every use. 21 of 88 transcripts on disk carry forkedFrom — 23.9%
§4.4	"Edge cases (v1 ignores them; re-pin manually if hit): explicit --fork-session …"	The premise that forking is rare is false, so pins drift routinely — confirmed against the live session-marks.json

Both are kept visible as corrections rather than deleted. A stale claim that simply disappears leaves anyone who saw it elsewhere still believing it; a claim marked wrong does not.

New §4.7

Records what the experiment established, so it is not re-derived:

• /branch copies the transcript to a new sessionId while the same process keeps writing — pid unchanged, sessions/<pid>.json updated in place, parent left intact and resumable.
• Claude Code writes the parent link itself: "forkedFrom": { "sessionId", "messageUuid" }, absent from root transcripts. One extra grep pattern in the enrichment scan gives an exact child → parent map — no heuristics, and content comparison would not have worked (the copy is not byte-identical).
• The transcript is copied; history.jsonl is not. That single asymmetry produces all four symptoms: deep search finds the parent, messageCount reads "1 msgs" for a full conversation, pins stay behind, and ordering lifts abandoned ancestors above the work.
• The sharper problem is identity, not the chain: /branch moves you into the new session, so the name lands the wrong way round. The daily workaround is a three-step rename swap, done because /branch carries in-flight subagents into the child — the task really does continue there, so the name follows the work. Names are therefore deliberately reused, and three live sessions with identical names were observed at once, which also defeats iTerm2's title-based switching.

⇒ The missing abstraction is stable task identity across sessionIds. Pin drift, search pointing at ancestors, and indistinguishable rows are one gap surfacing in three places. Worth designing before building the individual fixes.

A method note is included as well: ~/cc-session-snap.sh (sessionId / pid registration / transcripts / history.jsonl tail, diffed either side of an action) is what turned "resume sometimes seems confused" into the numbers above, and it is the tool for the still-open /fork question.

Also

Status header updated — §4.5 row readability shipped as PR #139.

No code changes; no tests affected.

🤖 On behalf of @grimmerk — generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated session-finding documentation with results from a live experiment.
  • Corrected details about session creation and pin behavior, including measured transcript usage.
  • Added coverage of generation chains, linked sessions, ordering effects, and task identity limitations.
  • Revised the status of a previously characterized workflow to reflect that it remains active.

---

Summary by cubic

Updates docs/session-finding-plan.md to correct two load-bearing assumptions a live /branch experiment falsified, records what the experiment established in new §4.7, and points status tracking at issue #144.

Changes

• The experiment (issue #142) found /branch creates a generation chain on every use: 21 of 88 transcripts (23.9%) carry forkedFrom.
• The falsified claims stay visible as marked corrections instead of being deleted, so readers who saw the old text elsewhere learn it was wrong.
• New §4.7 records that /branch copies the transcript to a new sessionId while the same process keeps writing, but does not copy history.jsonl — which explains why search finds the parent, messageCount reads "1 msgs", and pins drift.
• The underlying gap is stable task identity across sessionIds; pin drift, ancestor search, and indistinguishable rows are all symptoms of that missing abstraction.
• The status header now defers order, priority, and "is this done" questions to tracking issue #144, since a committed document cannot be corrected without a PR; row readability (§4.5) is marked shipped as PR #139.
• Docs only; no code changes and no tests affected.