ai-artifacts

Orchestrator for analyzing a single Claude Code session transcript. Takes the tmp folder produced by get-claude-code-transcript-from-local, requires the Segment tree from decompose-agent-transcript-into-transcript-segments (invoking it if the tmp folder doesn't already have one), drives the per-Segment analyzers across four buckets (outcomes, prompts, skills, mcp) and writes their conclusions as findings.<kind>.json — and stops there. It produces only that transcript's four findings files; there is no per-transcript report. The report is a batch-end step: once every transcript of interest has been analyzed, synthesize-agent-transcript-analysis-report runs once over the whole batch's findings. Use this skill when the user wants a single session analyzed, a "how could this have gone better" review, or to surface Skill/MCP opportunities from real usage.

Cross-cutting analyzer. Given the per-transcript findings.*.json sets of several already-analyzed transcripts (the phase-3 outputs of analyze-agent-transcript — findings.outcomes/prompts/skills/mcp.json), surface patterns that no single transcript reveals: Segments that could have been shorter with hindsight, user prompts that repeat the same nudges or context, recurring missing Skills / MCP tools across sessions, time-spend patterns where the agent consistently takes 5x what a human would. Still phase-3 labeling, but runs once over the whole batch — last in phase 3, after every transcript has been analyzed — as an optional pre-report augmentation, not interleaved per transcript and not fanned out by the orchestrator. Runs on the raw per-transcript findings; there is no per-transcript report, and reading raw findings is what catches the long tail that only matters in aggregate. Writes findings.cross-transcript.json into the batch_dir for synthesize-agent-transcript-analysis-report to pick up. Use this skill w

Per-Segment analyzer. Produces an improvement hypothesis for every Failure Outcome and every retro-Failure (a Correction trigger at the next Segment's head implies the prior Segment failed even if it didn't recognize it). Both user-source and agent-source Corrections qualify as retro-Failure signals; user-source is the stronger signal. Each hypothesis names the most plausible root cause — usually a missing Skill, a Skill whose description didn't trigger, a missing MCP capability, or a user-side prompting issue — and the concrete change that would have prevented the failure. Fed by analyze-agent-transcript; outputs flow into the Prompting / Skills / MCP recommendation buckets of the final report.

Per-user-source-New-Trigger analyzer (the case formerly known as the Initial Prompt). Flags user-typed Triggers that look like they under-scoped the work — short, narrow, followed quickly by another user-source New Trigger on a related Goal. Pattern suggests the user split work the agent could have one-shotted with a more ambitious prompt. Output feeds the human-prompting recommendation bucket, and may also surface deterministic-trigger opportunities (the ideal end-state for user-source New Triggers).

Analyze a single user-source Trigger attached to a Transcript Segment. Classify it (question vs delegation), confirm the Segment's Goal, and assess whether the Segment closed the loop on that Goal. The Trigger kind (New vs Correction) and source (user) are already set by the segmenter; this skill consumes them. If the Goal isn't self-evident, delegate to pull-together-agent-transcript-goal-context. Output feeds the "human prompting" recommendation bucket of analyze-agent-transcript.

Phase-4 synthesis — runs once over a whole batch of analyzed transcripts. Given the per-transcript tmp_dirs that make up the batch, reads every transcript's phase-3 findings (findings.outcomes/prompts/skills/mcp.json) plus findings.cross-transcript.json when present, and synthesizes them into ONE final report of actionable next steps across three buckets: human prompting, Skills (create/modify/delete), and MCP servers (create/modify/delete). Writes findings.report.json (the reviewable recommendation slate) and report.md (the human-readable report grouped by priority, including a key-stats block aggregated across the batch), and a multi-page HTML site that drills from the report down into every intermediate decision the pipeline made — report.html landing + recommendations/rec-NNN.html per rec + sessions/<tag>.html per transcript + segments/<tag>--<SID>.html per Segment (its decomposition plus every phase-3 finding tagged to it) + optional external-context and cross-transcript pages — into a batch_dir. Use onc

For a given transcript, gather the external context a reviewer would want before judging the session: the ticket the work traces back to (e.g. from Jira), the pull request it landed in (e.g. from GitHub), and background on the user's role, team, and project. Reads transcript.json from get-claude-code-transcript-from-local, infers what to look up from the session's cwd / git remote / branch / prompts, pulls it from whatever systems are reachable, and consolidates everything into one external-context.json that travels with the transcript through every later phase. Use after get-claude-code-transcript-from-local and before decompose-agent-transcript-into-transcript-segments. Best-effort: missing sources are recorded, never fatal. The set of sources is expected to grow over time.

Given the tmp folder produced by get-claude-code-transcript-from-local (containing transcript.json — an OpenTranscripts Transcript document), decompose the transcript into a recursive tree of Transcript Segments (see the transcript-segment reference). Each Segment carries a Trigger (kind: New | Correction × source: user | agent | subagent), a Goal (Plan | Action), an Outcome (Success | Failure), child sub-segments, and a meta block (event range, wall-clock, tokens, model). Emits segments.json (structured) and flamegraph.html (annotated). All phase-3 analyzers read segments.json — they never walk transcript.json events directly. Use this skill immediately after acquisition and before any analyze-* skill.

List all Claude Code session transcripts on this machine and let the user (or the agent) pick which one to analyze. Use this skill when the user wants to "find a session", "browse transcripts", "look at recent agent work", or as the first step of an analysis flow that doesn't yet have a target session id. Reads from `~/.claude/projects/` and spawns a local browser UI for selection.

Given a Claude Code session id (or a JSONL path), produce a single OpenTranscripts `transcript.json` — the main session plus every subagent it spawned, linked and nested in one self-contained JSON document. The CC → OpenTranscripts mapping is deterministic (no LLM, no heuristics) per the open-transcripts-claude-code-mapping reference, and secret-redaction runs inline. Use this skill after find-all-claude-code-transcripts-on-local (or when the session id is already known) and before any of the analyze-* skills. The output is a path to a tmp directory containing transcript.json conforming to the open-transcripts-transcript reference.

For each MCP tool call in a Transcript Segment, assess whether the call helped or hurt the Segment's Goal, whether its response shape was usable, and whether its token cost was proportionate. Output recommendations to modify tool implementations or response shapes — or to delete tools that are net-negative.

Within a Transcript Segment, identify MCP servers / tools that don't exist yet but should — moments where the agent could not close a loop because the relevant external system was unreachable from inside the session. Most often surfaced when the user tried to write a one-shot prompt and could not, or when the agent hand-rolled a brittle CLI workaround. Also seeded by analyze-agent-transcript-failure-hypothesis (missing_mcp_tool) and by analyze-agent-transcript-prompt-ambition (deterministic_trigger_candidate). Outputs proposals for new MCP servers or new tools on existing servers.

Within a Transcript Segment, identify MCP tools that were called when they shouldn't have been (false positives) and MCP tools that should have been called but weren't (false negatives — e.g. the agent reached for a CLI or hand-rolled an HTTP request when an available MCP tool would have done the job). Output recommendations to modify or delete MCP tool surfaces.

Per-Segment efficiency analyzer. Compares the Segment's actual wall-clock and token spend to a reasonable human-or-tighter-agent counterfactual, and flags two patterns: (a) wasteful branches — detours that, in hindsight, weren't on the critical path; (b) model-size mismatch — Segments where a smaller/faster model would have served, or where the chosen model was under-powered and the Segment thrashed. Outputs feed the Skills / MCP recommendation buckets when the inefficiency points at a tooling fix.

Build context around what a user was trying to accomplish in a Transcript Segment when the Goal is not self-evident from the user message (segment.trigger.text) alone. Reaches into git repos (commits, PRs, branch state at the time of the session), issue trackers, and any other systems referenced in the message. Use this skill when analyze-agent-transcript-user-prompt cannot confidently confirm a Goal.

For each Skill that was actually invoked in a Transcript Segment, assess whether it helped or hurt the Segment's Goal, and whether its token / turn cost was proportionate. Output recommendations to modify the body of Skills that underperform, or to delete Skills that are net-negative.

Within a Transcript Segment, identify Skills that don't exist yet but should — moments where a well-placed Skill would have saved turns or prevented a wrong turn. Outputs proposals for new Skills (name, description, body sketch) anchored to the philosophy doc. Often seeded by analyze-agent-transcript-failure-hypothesis when a Segment's root-cause class is missing_skill or non_triggering_skill.

Within a Transcript Segment, identify Skills that triggered when they shouldn't have (false positives) and Skills that should have triggered but didn't (false negatives). Output recommendations to modify Skill descriptions, or to delete Skills that consistently misfire.