Method Sessions

---
name: method-sessions
description: "Searches and summarizes prior coding-agent session history without reproducing sensitive logs. Use when the user asks what was tried before or what past sessions decided."
---

# `method-sessions`

## Skill Value

- **Problem it solves:** Prior attempts, decisions, and blockers are hard to recover from raw session files.
- **Use when:** The user asks what happened before, what was tried, prior decisions, or session-history questions.
- **Output:** A technical synthesis with relevant attempts, outcomes, and caveats.
- **Ask only if:** Only when the session question or scope is missing.
- **Do not do:** Do not quote sensitive session content or expose credentials.
- **Interaction:** Check repo/config/chat evidence first. Ask one decision-changing question at a time; use the current harness's blocking question UI when available, otherwise present numbered choices and wait.

Search session history across Claude Code, Codex, and Cursor and synthesize findings about what was worked on, tried, decided, or learned in prior sessions.

## Usage

```
`method-sessions` [question or topic]
`method-sessions`
```

## Pre-resolved context

**Git branch (pre-resolved):** !`git rev-parse --abbrev-ref HEAD 2>/dev/null || true`

If the line above resolved to a plain branch name (like `feat/my-branch`), use it for branch filtering and pass it to the synthesis subagent. If it still contains a backtick command string or is empty, derive the branch at runtime instead.

**Repo root (pre-resolved):** !`git rev-parse --show-toplevel 2>/dev/null || true`

If the line above resolved to a path, take its last path component as the repo folder name and use that for session discovery. If it is empty or still contains a backtick command string, derive the repo name at runtime instead.

## Current year

Resolve the current year at runtime (`date +%Y`) rather than assuming one; use it when interpreting session timestamps.

## Guardrails

- **Never read entire session files into context.** Session files can be 1-7MB. Always use the extraction scripts to filter first, then reason over the filtered output.
- **Never extract or reproduce tool call inputs/outputs verbatim.** Summarize what was attempted and what happened.
- **Never include thinking or reasoning block content.** Claude Code thinking blocks are internal reasoning; Codex reasoning blocks are encrypted. Neither is actionable.
- **Never analyze the current session.** Its conversation history is already available to the caller.
- **Surface technical content, not personal content.** Leave out credentials, frustration, and half-formed opinions.
- **Fail fast on access errors.** If session discovery fails on permissions, report the issue immediately. Do not retry the same operation with different tools or approaches.

## Execution

When this skill asks a user-facing question, follow the Skill Value interaction rule above.

### Step 1 — Determine scan window

Infer a time range from the user's question. Start narrow; widen only if a narrow scan finds nothing relevant.

| Signal | Initial scan window |
|--------|---------------------|
| "today", "this morning" | 1 day |
| "recently", "last few days", "this week", or no time signal | 7 days |
| "last few weeks", "this month" | 30 days |
| "last few months", broad feature history | 90 days |

Claude Code retains session history for ~30 days by default. Wider windows may find nothing on Claude Code unless the user has extended retention.

### Step 2 — Discover sessions and extract metadata

Run the discovery + metadata pipeline (keep the null-delimited `xargs -0`):

```bash
SKILL_DIR="<absolute path of the directory containing this SKILL.md>";
bash "$SKILL_DIR/scripts/discover-sessions.sh" <repo> <days> | tr '\n' '\0' | xargs -0 python3 "$SKILL_DIR/scripts/extract-metadata.py" --cwd-filter <repo>
```

Each output line is a JSON object describing a session (platform, file, size, ts, session, plus platform-specific fields). The final `_meta` line carries `files_processed` and `parse_errors`.

If the inventory's `_meta` line shows `files_processed: 0`, return "no relevant prior sessions" and stop.

If `parse_errors > 0`, note that some sessions could not be parsed and proceed with what was returned.

To narrow the platform set, add `--platform claude`, `--platform codex`, or `--platform cursor` to the `discover-sessions.sh` invocation. Default to all three.

### Step 3 — Filter and rank

Apply these filters in order to pick the sessions worth deep-diving:

1. **Branch filter (Claude Code only).** Keep sessions where `branch` equals the git branch resolved above (or the branch a caller passed) exactly, or where the branch name contains a keyword from the question's topic (e.g., a question about "auth middleware" matches branches `feat/auth-fix`, `chore/auth-refactor`). Codex sessions don't carry `gitBranch` — skip this filter for them.

2. **If the branch filter returned zero sessions, or you're processing Codex sessions:**
   - Derive 2-4 keywords from the question's topic. For "a recent crash in the auth middleware where session-validation rejects valid tokens", derive `auth,middleware,session,token` (or similar).
   - Re-invoke the discovery pipeline with `--keyword K1,K2,...` appended to the `extract-metadata.py` invocation. The script returns sessions with non-zero `match_count` plus per-keyword counts.
   - **If `files_matched: 0`, return "no relevant prior sessions" and stop.** Do not extract anything.
   - If `files_matched > 0`, treat those sessions as candidates. Rank by `match_count`, break ties by per-keyword counts.

3. **Drop sessions outside the scan window.** Use `last_ts` when available, fall back to `ts`. Discard sessions where both fall before the window start.

4. **Exclude the current session** — its conversation history is already available to the caller.

5. **Apply the deep-dive cap.** Take at most **5 sessions total across all platforms**. Narrow by branch-match → `match_count` → file size > 30KB → recency.

6. **Proceed only if at least one session remains after filtering.** Otherwise return "no relevant prior sessions" and stop.

**Note: `gitBranch` is captured at the first user message only.** A session that began on `main` and did substantive work on a feature branch via mid-session `git checkout` records `branch: "main"`. Branch-match returning nothing is not conclusive evidence — that's why the keyword-filter fallback in step 2 is required.

### Step 4 — Set up scratch space

Create a per-run throwaway scratch directory:

```bash
SCRATCH=$(mktemp -d -t method-sessions-XXXXXX)
```

Capture the absolute path and thread it into Steps 5 and 6.

### Step 5 — Extract per-session content (file-mediated)

For each selected session, run the skeleton extractor with `--output` so content writes directly to the scratch file — extraction bytes never round-trip through the orchestrator's tool results:

```bash
SKILL_DIR="<absolute path of the directory containing this SKILL.md>";
python3 "$SKILL_DIR/scripts/extract-skeleton.py" --output "$SCRATCH/<session-id>.skeleton.txt" < <session-file>
```

Stdout receives only a one-line JSON status (`{"_meta": true, "wrote": "...", "bytes": N, ...}`). Capture `bytes` and `parse_errors` from each status line.

**Conditional tail view** — if a skeleton ends mid-investigation (last visible turn is an unresolved tool call, or debugging without a conclusion), inspect its end with `tail -n 50` on the scratch file. `extract-skeleton.py` has no tail cap; use this only when the head output suggests truncation.

**Conditional errors-mode** — for sessions where investigation dead-ends are likely valuable:

```bash
SKILL_DIR="<absolute path of the directory containing this SKILL.md>";
python3 "$SKILL_DIR/scripts/extract-errors.py" --output "$SCRATCH/<session-id>.errors.txt" < <session-file>
```

Use selectively — only when understanding what went wrong adds value. Cursor agent transcripts don't log tool results, so errors-mode produces nothing for Cursor sessions.

### Step 6 — Dispatch synthesis subagent

Dispatch the `method-session-historian` subagent via the platform's subagent primitive (`Agent` in Claude Code, `spawn_agent` in Codex, `subagent` in Pi via the `pi-subagents` extension). Omit the `mode` parameter so the user's configured permission settings apply. Run on the mid-tier model (e.g., `model: "sonnet"` in Claude Code).

The dispatch prompt is the agent's input contract. Pass these fields:

- `problem_topic` — one sentence naming the concrete question. Lift from the user's argument or, if missing, from the answer to the no-arg prompt.
- `scratch_dir` — absolute path to `$SCRATCH`.
- `sessions` — an array of objects, one per extracted session, each with:
  - `path` — absolute path to the skeleton file (and optionally `errors_path` for the errors file when extracted)
  - `platform` — `claude`, `codex`, or `cursor`
  - `branch` — git branch when present (Claude Code only)
  - `cwd` — working directory when present (Codex only)
  - `ts` and `last_ts` — session timestamps
  - `match_count` and `keyword_matches` — when keyword filtering was used
- `output_schema` — the structure the agent's response should follow. Default schema:
  ```
  Structure your response with these sections (omit any with no findings):
  - What was tried before
  - What didn't work
  - Key decisions
  - Related context
  ```
  When the caller (e.g., `method-compound`) supplies a schema in the skill argument, pass it through verbatim.

Example dispatch shape:

```
Synthesize findings from these prior sessions:

Problem topic: <one-line topic>

Sessions to read (paths in $SCRATCH; on macOS `mktemp -d -t` resolves under `$TMPDIR`, e.g. `/var/folders/.../T/method-sessions-XXXXXX`):
1. $SCRATCH/abc123.skeleton.txt
   platform=claude branch=feat/auth-fix ts=2026-05-01
2. $SCRATCH/def456.skeleton.txt  errors=$SCRATCH/def456.errors.txt
   platform=codex cwd=/Users/.../my-project ts=2026-05-03
...

Output schema:
- What was tried before
- What didn't work
- Key decisions
- Related context

Filter rule: only surface findings directly relevant to this specific problem.
Ignore unrelated work from the same sessions or branches.
```

The agent reads each path with the native file-read tool and returns prose findings; the orchestrator holds only file paths and inventory metadata.

### Step 7 — Return findings

Return the synthesizer's output text to the caller verbatim. If discovery or keyword filtering returned zero sessions (Step 2 or Step 3), return the literal string `no relevant prior sessions` instead.

Optionally clean up with `rm -rf "$SCRATCH"`.

## Output

When the caller (typically a user typing `method-sessions`, or another skill invoking method-sessions via the platform's skill-invocation primitive) does not specify an output format, include a brief header noting what was searched:

```
**Sessions searched**: [count] ([N] Claude Code, [N] Codex, [N] Cursor) | [date range]
```

Then the synthesizer's prose findings. When the caller supplies a schema, honor it verbatim and omit the default header.

## Time budget

Stop as soon as a complete answer is available. A confident "no relevant prior sessions" within seconds is a complete answer; do not extend the search to fill time.

## Error handling

If the discovery pipeline fails (e.g., unreadable home directory, permission failure), surface the error to the caller. Do not substitute git log, file listings, or other sources — this skill's contract is session metadata and synthesis.

If extraction `--output` write fails (disk full, permission), surface a clear error and do not dispatch the synthesizer with partial paths.

If `_meta` reports `parse_errors > 0` from any script, note partial extraction in the dispatch prompt and proceed; the synthesizer flags partial in findings.