AGENT SKILL

vs-search-threads

Search Codex, Claude Code, or Cursor threads, chats, transcripts, and transcriptions, then analyze what they contain. Use to find a past session or conversation, review a transcript, audit agent performance, compare sessions, locate loops or corrections, and extract decisions, outcomes, evidence, and actionable improvements.

License 许可
MIT
所属仓库
vltansky/vs
最近更新
2026-11-06
Stars
★ 0
Forks
1

01 前言 Front Matter

name
vs-search-threads
description
Search Codex, Claude Code, or Cursor threads, chats, transcripts, and transcriptions, then analyze what they contain. Use to find a past session or conversation, review a transcript, audit agent performance, compare sessions, locate loops or corrections, and extract decisions, outcomes, evidence, and actionable improvements.

02 资源文件 6

03 SKILL.md 正文

Search Threads

Turn one or more coding-agent conversations into an evidence-backed diagnosis. Support the active conversation, attached or exported transcripts, and local Codex or Claude Code JSONL history. Treat Cursor's Markdown export as its portable transcript contract.

Guardrails

  • Keep project files and transcript sources read-only unless the user explicitly asks to apply findings. A cross-session report under ~/.vs/ is output, not a source mutation.
  • Do not surface secrets, credentials, private keys, hidden reasoning, or raw chain-of-thought. Paraphrase sensitive evidence and omit reasoning events.
  • Separate agent behavior, tool or environment failures, user corrections, and task complexity. Similar symptoms can have different owners.
  • Label claims as verified, inferred, or unknown. A polished summary must not conceal missing transcript sections or unavailable tool results.
  • Quote only the smallest useful evidence fragment and identify its source and turn. Prefer paraphrase when a quote may contain private data.

Bound the investigation

Apply ../vs-internal-shared/references/bounded-collaboration.md before widening transcript collection. Infer the requested outcome, source scope, proof, artifact, authority, and stop triggers from the request. Reassess when acquisition fails at the same boundary again, the source set would expand, or the report cannot support its next claim. Resolve answerable facts yourself; ask only when the user must choose the session set, authority, or outcome.

1. Resolve scope

Use explicit transcript paths, thread IDs, pasted text, or the current conversation first. If the user says only "analyze this thread," analyze the active thread. If they ask for recent history without a count, use the three most recent project-matching sessions.

When the user names a thread by content instead of by path or ID ("the session where we fixed the auth bug"), search the host's history for those terms, rank candidates by recency and match strength, and confirm the chosen session before analyzing it. Report the shortlist when more than one session plausibly matches.

Ask only when choosing the wrong project, session set, or comparison baseline would materially change the result.

2. Acquire transcripts

Prefer host APIs or thread-reading tools when available. Otherwise use the narrowest local source that matches the request:

Host Preferred source Local or export fallback
Codex Active thread or thread-read tool ~/.codex/sessions/**/rollout-*.jsonl; match a supplied ID or session_meta.payload.cwd
Claude Code Active conversation ~/.claude/projects/<project-slug>/*.jsonl
Cursor Active chat or @Past Chats Export the chat as Markdown from History

Do not scrape Cursor's SQLite history by default. Its internal schema is not a portable contract; request a Markdown export if the active chat is insufficient. Background or remote-agent chats may require the host's own history surface.

To locate a session by content, search the host's history directory before normalizing anything, so only the matching files enter scope:

rg -l -i --glob '*.jsonl' '<search terms>' ~/.claude/projects/<project-slug>/ \
  | xargs -r ls -t | head -5

Print candidate paths and modification times, not transcript bodies.

For local JSONL or exported Markdown, normalize only the files in scope:

PROJECT_ID=$(git config --get remote.origin.url 2>/dev/null \
  | sed -E 's#\.git$##; s#.*[:/]([^/]+/[^/]+)$#\1#; s#/#-#g')
[ -z "$PROJECT_ID" ] && PROJECT_ID=$(basename "$PWD")
NORMALIZED_PATH="$HOME/.vs/$PROJECT_ID/thread-analysis/evidence/normalized-$(date +%Y%m%d-%H%M%S).md"
node "<skill-dir>/scripts/normalize-transcript.mjs" \
  --output "$NORMALIZED_PATH" <transcript-file> [more-files]

The normalizer writes user and assistant turns to disk with stable source and turn labels and creates a sibling .index.json turn index. Stdout contains only path, turn count, byte count, and SHA-256 metadata. Inspect the index first, then retrieve only the targeted turn or short adjacent turn range needed for a claim. For an unfamiliar transcript, discover candidates with a bounded search such as rg -n -i --max-columns 300 --max-columns-preview '<claim terms>' "$NORMALIZED_PATH" | head -50, map matching lines to the index, then slice those turns. Do not print the whole normalized file. It excludes system, developer, tool, and reasoning records. Read raw records only when diagnosing a specific tool failure, and summarize them rather than dumping them. Follow the disk-backed evidence contract.

If a transcript cannot be accessed, say exactly which source is unavailable and continue with the evidence that is available.

3. Build an evidence ledger

For every material claim, record:

  • source and turn or timestamp;
  • observed event;
  • classification: verified, inferred, or unknown;
  • owner: agent, user decision, tool/environment, or external dependency;
  • impact on the outcome.

Deduplicate repeated status messages and compacted copies of the same turn. Treat summaries as secondary evidence when original turns are present.

4. Analyze

Evaluate the conversation along these axes:

  1. Intent and outcome — what the user wanted, what was delivered, and what remains incomplete.
  2. Trajectory — the few turning points that changed the plan or result.
  3. Decisions and corrections — accepted choices, rejected assumptions, and durable preferences.
  4. Execution quality — useful actions, avoidable loops, premature claims, missed verification, and unnecessary interruptions.
  5. Failure ownership — agent mistake versus tool, auth, sandbox, network, repository, or external-state failure.
  6. Improvements — the smallest instruction, workflow, tooling, or product changes that would prevent recurrence.

Use metrics only when the transcript supports them. Useful measures include user corrections, repeated commands, failed tool calls, approval waits, and turns between request and verified outcome. Do not invent token counts, costs, durations, or success rates.

For comparisons, apply the same rubric to every transcript and explain material differences in task scope or environment before ranking agents or sessions.

5. Report

Lead with the diagnosis. A short single-thread analysis stays compact in Markdown in chat. A complex single-thread analysis uses HTMDX when it has three or more material turning points, repeated-field comparisons, or enough evidence and caveats to exceed one short screen. Follow the shared two-layer explanation contract: chat is the TLDR and the artifact is the visual human review surface. Omit empty sections; for a short thread, collapse the report to Bottom line, Findings, and Recommended changes.

# Thread analysis

## Bottom line
<outcome, main cause, and current state>

## What happened
- <turning point> — <source:turn> — verified|inferred

## Decisions and corrections
- <decision or durable preference> — <evidence>

## Friction
- <symptom> -> <cause or unknown> -> <impact>

## What worked
- <effective behavior and why it mattered>

## Recommended changes
1. <smallest high-value change> — owner: <agent|workflow|tool|product>

## Evidence gaps
- <missing or inaccessible evidence, or "None material">

For a cross-session comparison, use HTMDX because the repeated rubric, metrics, turning points, and evidence are easier to compare visually. Resolve the project ID and create the artifact directory. Choose a comparison slug from the session labels or comparison focus, using lowercase letters, numbers, and hyphens only:

PROJECT_ID=$(git config --get remote.origin.url 2>/dev/null \
  | sed -E 's#\.git$##; s#.*[:/]([^/]+/[^/]+)$#\1#; s#/#-#g')
[ -z "$PROJECT_ID" ] && PROJECT_ID=$(basename "$PWD")
REPORT_DIR="$HOME/.vs/$PROJECT_ID/thread-analysis"
REPORT_DATE=$(date +%F)
COMPARISON_SLUG="sessions"
REPORT_EXTENSION="html"
REPORT_BASE="$REPORT_DIR/thread-comparison-$REPORT_DATE-$COMPARISON_SLUG"
REPORT_PATH="$REPORT_BASE.$REPORT_EXTENSION"
SUFFIX=2
mkdir -p "$REPORT_DIR"
while ! (set -C; : > "$REPORT_PATH") 2>/dev/null; do
  REPORT_PATH="$REPORT_BASE-$SUFFIX.$REPORT_EXTENSION"
  SUFFIX=$((SUFFIX + 1))
done

Replace the generic sessions slug before resolving the path. The loop appends a numeric suffix before the extension (-2, -3, and so on) when the output already exists and atomically reserves the first free path, so concurrent runs cannot overwrite an earlier comparison. For HTMDX, copy references/thread-comparison-template.html into the reserved $REPORT_PATH. If population fails, report the reserved empty path instead of reusing it.

Edit only the HTMDX source block. Produce one canonical artifact with no Markdown twin, then return the bottom line and report path in chat. Follow the shared rich-artifact contract.

Apply the security boundary to the actual report content. Paraphrase and redact credentials, secrets, PII, and sensitive evidence. A sanitized comparison still uses HTMDX. If the user explicitly requests Markdown, or sensitive data must remain and no trusted local runtime is available, set REPORT_EXTENSION="md", run the same collision-safe path resolution, and write the comparison as $REPORT_DIR/thread-comparison-$REPORT_DATE-$COMPARISON_SLUG.md without copying the HTML template.

Do not write findings into rules, memories, issues, or skill files without a separate explicit request.

Output style

Apply the shared output style to every user-facing message.

Workflow

Direct: emit Next only. Composed: return to caller.

Prev: thread selection | transcript export Next: done | /vs-retro for reviewed learnings Relevant: /vs-recap | /vs-try-skill

04 同仓库更多 Skills