agent-wiki-extract-guidelines

Agent Wiki — Extract Guidelines

Overview

Distill lessons from one session at a time. For each normalized trajectory JSON, identify reusable guidelines: reframe failures as proactive recommendations, capture concrete artifacts (scripts, command sequences) that solved real problems, and write each as a standalone guideline page in wiki-twobatch/guidelines/.

This is the per-trajectory distill pass of the agent-wiki family.

Input

A path that is either:

• a normalized trajectory JSON file
• a directory of such files

Default if no path is given: trajectories/normalized.

Workflow

Step 1: Resolve input files

Use Glob to enumerate JSON files.

Step 2: Glance at existing guidelines

Glob wiki-twobatch/guidelines/*.md and skim slugs. Re-extracting a near-duplicate is wasteful and pollutes the wiki. (Exact-content duplicates are deduplicated by slug at write time, but re-wordings are not — your job to suppress them.)

Step 3: Process each trajectory

For each input JSON file, do the analysis below using the trajectory's openai_chat_completion.messages array as the source of truth.

3a. Identify errors and root causes

Scan for:

1. Tool / command failures — non-zero exit codes, error messages, stack traces.
2. Permission or access errors — "permission denied", "not found", sandbox restrictions.
3. Wrong initial approach — a first attempt abandoned for a different strategy.
4. Retry loops — same action attempted multiple times with variations.
5. Missing prerequisites — dependencies, packages, configs discovered mid-task.
6. Silent failures — actions that appeared to succeed but produced wrong results.

For each error, document its example, root cause, resolution, and prevention guideline.

3b. Decide whether to capture an artifact

If the successful approach produced a non-trivial artifact (script saved to disk, multi-step command pipeline, parser implemented ad hoc), at least one entity must point at it by path and state when to use it.