find-related-sessions

name	find-related-sessions
description	Use when the user references a SPECIFIC FILE in a coding task — "fix the bug in routes/cost.py", "what was that change to api.ts about", "refactor stackunderflow/store/queries.py", or any request that names a path. Surfaces past sessions that read or wrote that file so the work is grounded in prior context (recent edits, why the file is shaped that way, half-finished refactors).

Find sessions related to a specific file

Why this skill exists

When the user mentions a specific file, prior work touching that file is the highest-signal context available. StackUnderflow's per-message tool index records which files each session read or wrote. One CLI call returns the recent sessions that touched the path — so you know what the last change was, why it was made, and whether the user's current request continues or contradicts it.

When this skill fires

Trigger when the user's request includes a concrete file path (with extension or recognizable file shape), AND the request is non-trivial (modify, fix, explain-in-context, refactor):

• "Fix the bug in routes/cost.py"
• "What was that change to api.ts about?"
• "Why is stackunderflow/store/queries.py so long?"
• "Refactor src/components/Dashboard.tsx"
• "Can you look at tests/test_aggregator.py?"

Do NOT fire for:

• Pure read requests with no follow-up ("show me foo.py")
• File paths in error messages or stack traces (use only when the user is explicitly directing attention there)
• Path-shaped strings that aren't real files (URLs, config keys)

Step 1: surface sessions touching the file

stackunderflow find-sessions-touching-file <path> --format json --limit 5 --mode any

The <path> argument can be relative to the user's cwd or absolute — both work. The CLI normalizes against the project's session index.

--mode filters by access type:

• any (default) — sessions that read OR wrote the file
• read — sessions that opened/grepped the file
• write — sessions that edited the file (highest signal for "what changed and why")

For most requests, --mode any is right. If the user says "what changed in this file", switch to --mode write to focus on edits.

JSON shape (one entry per session):

{
  "sessions": [
    {"session_id": "...", "project_slug": "...", "project_path": "/abs/path",
     "provider": "claude", "first_ts": "...", "last_ts": "...",
     "message_count": 42, "cost_usd": 0.85, "snippet": "first user message"}
  ]
}

Step 2: read the snippets, prioritize recency

Sessions come back newest-first. The snippet summarizes what each session was about. For a "what changed" question, the most recent session that wrote the file is usually the answer. For a "why is this shaped this way" question, scan the last several sessions for the design discussion.

Step 3: ground the work

• If a recent session refactored or rewrote the file: don't redo work the user already accepted. Mention what was done; ask if the new request supersedes or extends it.
• If the file was the subject of an unfinished change: pick up where that session left off.
• If no sessions touched the file in the indexed window: just proceed with the task. (sessions: [] is a valid result — find-sessions-touching-file is cheap to run speculatively.)

Showing the user vs. consuming internally

Default --format json is for agent consumption. When the user asks "show me sessions that touched X" or "when was Y last edited", use the human-readable form:

stackunderflow find-sessions-touching-file <path> --mode write --limit 10

Text output is sorted newest-first with timestamps and one-line snippets — readable as a changelog of who-touched-what.

Alternate path: MCP

If the StackUnderflow MCP server is connected, the equivalent is the find_sessions_touching_file tool with the same arguments. The CLI is the fallback because it's universally available.

Cost

Local SQLite query — no network, no LLM call. <100 ms even on large stores. Run liberally.