agent-wiki-summarize

Agent Wiki — Summarize Trajectory

Overview

Witness one session at a time. For each normalized trajectory JSON, author a 1–3 paragraph narrative + key turns + (when present) a classification of each recalled guideline as followed | ignored | contradicted with an evidence quote.

This is the per-trajectory witness pass of the agent-wiki family. It writes one page per session and tail-calls the bookkeeping catalog subcommand so indexes stay fresh.

Input

A path that is either:

• a normalized trajectory JSON file
• a directory of such files (recurse one level into <label>/items/)

Default if no path is given: trajectories/normalized.

Workflow

Step 1: Resolve input files

Use Glob to enumerate *.json. Accept either a single file, a flat dir of files, or a normalized/ root with <label>/items/ subdirs.

Step 2: Glance at existing summaries

Glob wiki-twobatch/summaries/*.md so you can skip-if-exists per session without re-doing LLM work. Skip is the default; pass --rewrite (forwarded to the helper below) to overwrite.

Step 3: For each trajectory JSON

Read the file. The fields you need:

• session_id, agent, model, started_at/ended_at/duration_seconds
• stats.top_tools (for tools_used)
• source.transcript_path
• openai_chat_completion.messages
• recalled_guidelines (top-level; may be empty/missing)

If wiki-twobatch/summaries/<session_id>.md already exists and the user did not request --rewrite, skip to the next file.

Otherwise synthesize a summary as a JSON object:

{
  "session_id":      "<from JSON>",
  "slug":            "<optional; for splitting a long session into multiple arc-summaries (e.g. 'arc1-token-savings'). When present, filename becomes <sid>__<slug>.md and frontmatter gains `arc:` plus a `sibling_summaries:` list of co-summaries from the same session.>",
  "agent":           "<from JSON, default 'claude-code'>",
  "model":           "<from JSON>",
  "goal":            "<one short sentence describing what the user asked for>",
  "outcome":         "success | partial | failure",
  "duration_seconds": <number from JSON>,
  "tools_used":      ["<from stats.top_tools, name only>", "..."],
  "narrative":       "<1-3 paragraphs: what happened, what worked, what didn't>",
  "key_turns":       ["<one short bullet per pivotal step>", "..."],
  "normalized_path": "<path to the JSON, relative to repo root>",
  "transcript_path": "<from source.transcript_path>",
  "recalled_guidelines": [
    {
      "id":       "<12-hex-char id of the guideline that was used in this session>",
      "title":    "<a short label, 3-7 words>",
      "status":   "followed | ignored | harmful | contradicted",
      "evidence": "<verbatim quote ≤200 chars; required for followed/harmful/contradicted>"
    }
  ]
}