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>"
    }
  ]
}

Rules of thumb:

• goal is one sentence; pull from the first user message.
• outcome is your judgement.
• narrative is short (≤ ~250 words). No fluff.
• key_turns is 3–6 bullets at most. Each one sentence.
• Skip recalled_guidelines entirely if no guidelines were available or used.
• Quotes must be verbatim (thinking / assistant text / tool_use args / tool_result content); ≤200 chars; ellipsize with … if cut.

How recalled_guidelines is populated

The recalled_guidelines field captures every wiki guideline the agent saw in this session. Scan the trajectory for the agent reading guideline files from a wiki dir — <wiki-root>/guidelines/<slug>__<gid>.md or <wiki-root>/guidelines/<slug>__cluster.md — either via the Read tool or via Bash cat/less/grep. Extract each file's id from its YAML frontmatter (id: <12-hex>) so the row links to the wiki's _id_index.json.

Don't double-count: if the agent reads the same guideline file twice, emit one row.

Status vocabulary (4-way)

You judge the status from trajectory evidence, not the agent's self-report:

• followed — the agent acted on the guideline and the action produced the intended result. Required evidence: a verbatim quote showing the agent applied the rule (citation, paraphrase that triggered a tool call, or a tool call whose form matches the guideline's prescription).
• ignored — the agent read the guideline file but never acted on it. No evidence needed; default for guidelines that landed in context without effect.
• harmful — the agent acted on the guideline and it led astray: wasted tool calls, wrong path, retracted decision, or surfaced a wrong answer that had to be corrected. Required evidence: a verbatim quote showing the bad outcome that followed application.
• contradicted — the agent saw the guideline and deliberately did the opposite (disagreed with the rule). Required evidence: a verbatim quote where the agent's action contradicts the guideline's prescription.

Default to ignored when uncertain. Don't assign followed or harmful without a verbatim evidence quote — those carry signal value only when backed by trajectory text.