session-reflect
/session-reflect
Analyze a user's pi coding-agent session history for recurring behavior, prompting habits, workflow loops, friction, and preferences. Use when the user asks to inspect or reflect on pi sessions, common behavior patterns, agent/user interaction style, prompting habits, or personal pi workflow quality.
Assessment and security
- Files in this package
- 13
- Scripts
- 7
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 04.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 7 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/output.ts, scripts/session-db.ts, scripts/sql.ts, tests/output.test.ts, tests/session-db.integration.ts, tests/sql.test.ts, types/session-reflect-deps.d.ts
What it does and when to use it
Analyze a user's pi coding-agent session history for recurring behavior, prompting habits, workflow loops, friction, and preferences. Use when the user asks to inspect or reflect on pi sessions, common behavior patterns, agent/user interaction style, prompting habits, or personal pi workflow quality.
Original author description
Analyze a user's pi coding-agent session history for recurring behavior, prompting habits, workflow loops, friction, and preferences. Use when the user asks to inspect or reflect on pi sessions, common behavior patterns, agent/user interaction style, prompting habits, or personal pi workflow quality.
How it works
- Data location
- Core rules
- Helper script
- Recommended workflow
- Output shape
SKILL.md preview
--- name: session-reflect description: Analyze a user's pi coding-agent session history for recurring behavior, prompting habits, workflow loops, friction, and preferences. Use when the user asks to inspect or reflect on pi sessions, common behavior patterns, agent/user interaction style, prompting habits, or personal pi workflow quality. --- # 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: ```text ~/.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: ```bash cd <dot-pi>/skills/session-reflect npm install ``` Typical first step: ```bash npx tsx scripts/session-db.ts build ``` If the user points to another session root: ```bash npx tsx scripts/session-db.ts build --root <session-root> ``` Useful evidence commands: ```bash 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 ..." ``` Use `--format table|json|markdown` before the subcommand when output will be read by the agent or quoted in a report: ```bash npx tsx scripts/session-db.ts --format markdown preset exact-short-repeats npx tsx scripts/session-db.ts --format json context <message_key> ``` Read [references/query-cookbook.md](references/query-cookbook.md) when selecting SQL queries. Read [references/reflection-protocol.md](references/reflection-protocol.md) before producing a user-facing reflection. Read [references/intervention-events.md](references/intervention-events.md) when analyzing shouting, profanity, corrections, frustration, stop/pause requests, evidence challenges, or any high-signal user redirect. ## Recommended workflow 1. Clarify scope: recent sessions vs all sessions, coding-only vs all Pi use, and desired output depth. 2. If the task is reflection over a large history, extract user messages first. Use them to identify candidate workflows and repeated corrections; retrieve assistant/tool context only around selected examples. 3. Build or refresh the DuckDB evidence database with `scripts/session-db.ts build`. 4. Run a bounded first-pass evidence set: `overview`, `exact-short-repeats`, `tools`, `long-sessions`, and `sample --turns 3 --examples 2`. Add n-grams only when exact repeats do not explain enough. 5. Pick surprising evidence leads and retrieve compact context windows around representative message keys. For repeated exact turns, use `examples --text ...` for targeted sampling or `sample` for time-spread examples across top repeated turns. Use `--compact --hide-tools` first; rerun without them only when tool output matters. 6. For friction analysis, treat candidate events as broad **interventions**, not just profanity/escalation. Use `references/intervention-events.md` before generalizing. 7. Run targeted searches for explicit current-user preferences mentioned in the conversation, then inspect context. 8. Reason manually from evidence; do not let preset names, query names, repeated phrases, profanity, or all-caps become conclusions. 9. Present a concise reflection with citations and confidence levels. 10. Ask whether the user wants tooling changes, pi prompt/default changes, or deeper follow-up analysis. ## Output shape Use this structure unless the user asks otherwise: ```markdown # Pi session behavior reflection ## Evidence inspected - Database/session scope - Query types used ## Observed patterns For each pattern: - Observation - Evidence - Interpretation - Confidence - Alternative explanation ## Friction / failure modes ## Preferences inferred from behavior ## Recommendations to test ## Open questions ```
Files in this package (13)
- SKILL.md 7 KB
- package.json 1 KB
- tsconfig.json 1 KB
- references/intervention-events.md 6 KB
- references/query-cookbook.md 7 KB
- references/reflection-protocol.md 3 KB
- scripts/output.ts 1 KB
- scripts/session-db.ts 27 KB
- scripts/sql.ts 8 KB
- tests/output.test.ts 1 KB
- tests/session-db.integration.ts 3 KB
- tests/sql.test.ts 1 KB
- types/session-reflect-deps.d.ts 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · dannote/dot-pi | 100 | MIT |
| h2xd/skills | 100 | MIT |
| linanwx/nagobot | 100 | MIT |
| nicknisi/sessions | 100 | MIT |
Database snapshot: 13.11.2026 · package version 0dc6ae9b7acc (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100reflect-on-conversation
Analyze conversation history for a structured retrospective on prompting, agent performance, system gaps, and efficiency. Use when wanting insights to improve collaboration or workflows. - 100reflect
Review the current chat session to identify mistakes, friction, and unclear outputs. Propose improvements and check any skills used for optimization opportunities. Use when correcting course or at session end. - 90reflect
Use when the session-reflect Stop hook requests a session wrap-up review, or when the user runs /reflect — 回顧本次 session 的任務、交談與工作環境的摩擦,triage 後從五視角(含環境摩擦)提出經驗證的最多 5 個改進建議,互動勾選執行,未選項寫入 backlog。routine 或無實質內容、且沒有摩擦事件的 session 直接回報「無需回顧」。 - 100reflect
Analyze the current session and propose improvements to skills. **Proactively invoke this skill** when you notice user corrections after skill usage, or at the end of skill-heavy sessions. Also use when user says "reflect", "improve skill", or "learn from this". - 96reflect
Drafts lessons from friction in a Claude Code session (a correction, a failing command, a denied permission) and hands them to brain propose. Use only when a brain hook message asks for shadow reflection. - 100reflect
Review current conversation, analyze tasks, errors, and user feedback, extract learning opportunities for skill improvement. Use when user says "reflect", "review session", "what did we learn", "session summary", or after completing a complex task.