Skip to content
Skills Library
AI & agents · Analysis

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.

Repository
dot-pi ↗
Licence
MIT
Last repository change
04.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
13
Scripts
7
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Data location
  2. Core rules
  3. Helper script
  4. Recommended workflow
  5. Output shape
Original SKILL.md headings · 132 lines, 816 words
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

RepositoryScoreLicence
This page · dannote/dot-pi100MIT
h2xd/skills100MIT
linanwx/nagobot100MIT
nicknisi/sessions100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.