Self-Improve
Analyze Pi sessions to improve agent behavior.
Goals
Goal Method
Pattern Discovery Find repeating prompts/workflows
Failure Analysis Identify recurring tool errors
Outputs
File Purpose
agent/skills/<name>/
Multi-step workflows
agent/prompts/<name>.md
Single prompts with args
agent/extensions/guardrails/defaults.json
Block/confirm dangerous patterns
agent/extensions/hooks/defaults.json
Auto-format/lint after changes
AGENTS.md
Project-specific rules
agent/APPEND_SYSTEM.md
Universal agent manifesto
Session Tools
List Projects/Sessions
pi-list-projects pi-list-sessions --project "my-project" --limit 10
Analyze Tool Calls
pi-tool-calls pi-tool-calls --errorsOnly pi-tool-calls --tool "bash:jj" --days 7
Search Events
pi-session-events --days 30 --limit 200 pi-session-events --query "refactor" --days 30
Read Sessions
pi-read-session --session 0 pi-read-session --session 0 --role toolResult --query "error"
Workflow
- Gather Data
pi-session-events --days 30 --limit 200 pi-tool-calls --errorsOnly --days 7
- Identify Patterns
Repeating prompts:
-
Common verbs: "create", "refactor", "describe", "split"
-
Similar structures with variable parts
-
Multi-step workflows
Tool failures:
-
Edit: "Could not find exact text"
-
Bash: grep exit 1, jj syntax errors
-
Recurring error messages
- Prioritize
Factor High Value
Frequency Appears 3+ times in 30 days
Complexity Takes 5+ tool calls
Error-prone Recurring failures
Repetitive Same steps with minor variations
- Create Improvements
Based on findings, update appropriate files.
APPEND_SYSTEM.md Format
New sections use numbered Roman headings with Against or For stance (## N. Against X or ## N. For X ). Prose paragraphs, no bullet lists, no bold markers, no indented context blocks. Declarative statements in first person. General principles, no project-specific tool names or examples. Read existing sections before adding new ones — match the style exactly.
Common Failure Patterns
Edit Tool
Pattern Fix
"Could not find" Read file first, use smaller edits
"No changes made" Verify content differs
Bash Tool
Pattern Fix
grep exit code 1 Use grep ... || true
jj "ambiguous" or "^ is not" Use @- for parent
Output Formats
Skill
agent/skills/<name>/SKILL.md
Multi-step workflows with tool sequences.
Prompt Template
name: template-name args: param: description: Parameter description default: "@"
Template content with {{param}}
Guardrail
{ "pattern": "^dangerous-cmd", "action": "block", "reason": "explanation" }
Hook
{ "event": "tool_result", "pattern": "\.ext$", "command": "formatter "${file}"" }
Related Skills
- skill-authoring: Write discovered skills