session-reflect

Session Reflect

Use this skill to help the user understand their own pi usage patterns from local session logs.

Data location

By default this skill writes only to:

~/.pi/agent/cache/session-reflect/

It never writes analysis databases into the current project by default. Use --db only when the user explicitly asks for another location. Use clean to remove the default cache.

The skill's job is evidence retrieval + agent judgment. Do not turn the helper script into the analyst. Use the script to load/search/query session evidence; use your own reasoning to infer patterns cautiously.

Core rules

• Discuss the analysis approach before implementing new tooling or making broad claims.
• Do not hardcode English behavior categories or phrase lists as conclusions.
• Treat repeated text, n-grams, FTS hits, and SQL aggregates as evidence leads, not interpretations.
• Inspect surrounding context before interpreting short user turns like “go ahead” or “what next”.
• Preserve multilingual text, typos, shorthand, pasted logs, and frustration markers as meaningful evidence.
• Cite session paths or message keys for important claims.
• Separate: observed facts, interpretations, confidence, alternative explanations, recommendations.
• When the current user message is itself a high-signal intervention, follow the recovery protocol in references/intervention-events.md before continuing.

Helper script

Use scripts/session-db.ts as a local evidence workbench. It loads pi JSONL sessions into DuckDB and exposes SQL/search/context helpers.

Install helper dependencies from the skill directory if they are missing:

cd <dot-pi>/skills/session-reflect
npm install

Typical first step:

npx tsx scripts/session-db.ts build

If the user points to another session root:

npx tsx scripts/session-db.ts build --root <session-root>

Useful evidence commands:

npx tsx scripts/session-db.ts doctor
npx tsx scripts/session-db.ts preset --list
npx tsx scripts/session-db.ts preset overview
npx tsx scripts/session-db.ts preset exact-short-repeats
npx tsx scripts/session-db.ts preset long-sessions
npx tsx scripts/session-db.ts turns --role user --limit 80
npx tsx scripts/session-db.ts turns --role user --short --limit 100
npx tsx scripts/session-db.ts ngrams --n 2 --min-count 3 --limit 50
npx tsx scripts/session-db.ts ngrams --n 3 --min-count 3 --limit 50
npx tsx scripts/session-db.ts search "literal or fuzzy lead" --role user --limit 25
npx tsx scripts/session-db.ts context <message_key> --before 4 --after 8
npx tsx scripts/session-db.ts context <message_key> --before 4 --after 8 --compact --hide-tools
npx tsx scripts/session-db.ts examples --text "Go ahead." --limit 5 --before 3 --after 5
npx tsx scripts/session-db.ts sample --turns 5 --examples 2 --before 3 --after 5
npx tsx scripts/session-db.ts interventions --limit 30 --min-score 2 --sort score
npx tsx scripts/session-db.ts interventions --limit 30 --min-score 2 --sort recent
npx tsx scripts/session-db.ts interventions --signal autonomy_boundary,evidence_challenge --limit 20
npx tsx scripts/session-db.ts interventions --project quackdb --since 2026-06-01 --limit 20
npx tsx scripts/session-db.ts interventions --sample --limit 10 --min-score 2
npx tsx scripts/session-db.ts interventions --pasted include --limit 20 --min-score 2
npx tsx scripts/session-db.ts interventions --pasted only --limit 20 --min-score 2
npx tsx scripts/session-db.ts interventions --context --limit 10 --min-score 2 --sort recent --before 4 --after 6
npx tsx scripts/session-db.ts sql "select ..."