Skip to content
Skills Library
Personal productivity · Automation

Reconstruct

/Reconstruct

Retroactively create session notes from JSONL transcripts and git history when automatic capture failed or was incomplete. USE WHEN user says 'reconstruct sessions', 'rebuild session notes', 'recover session notes', 'retroactively create notes', 'create notes from git history', 'notes are missing', 'backfill session notes', 'reconstruct what we did', OR /reconstruct.

Author
mnott ↗
Repository
pai ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

95/ 100Class: good
Format20 / 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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

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

What it does and when to use it

Retroactively create session notes from JSONL transcripts and git history when automatic capture failed or was incomplete. USE WHEN user says 'reconstruct sessions', 'rebuild session notes', 'recover session notes', 'retroactively create notes', 'create notes from git history', 'notes are missing', 'backfill session notes', 'reconstruct what we did', OR /reconstruct.

Triggers from the description

reconstruct sessionsrebuild session notesrecover session notesretroactively create notescreate notes from git historynotes are missingbackfill session notesreconstruct what we did
Original author description

Retroactively create session notes from JSONL transcripts and git history when automatic capture failed or was incomplete. USE WHEN user says 'reconstruct sessions', 'rebuild session notes', 'recover session notes', 'retroactively create notes', 'create notes from git history', 'notes are missing', 'backfill session notes', 'reconstruct what we did', OR /reconstruct.

How it works

  1. Reconstruct Skill
Original SKILL.md headings · 229 lines, 1,215 words
SKILL.md preview
---
name: Reconstruct
description: "Retroactively create session notes from JSONL transcripts and git history when automatic capture failed or was incomplete. USE WHEN user says 'reconstruct sessions', 'rebuild session notes', 'recover session notes', 'retroactively create notes', 'create notes from git history', 'notes are missing', 'backfill session notes', 'reconstruct what we did', OR /reconstruct."
---

## Reconstruct Skill

USE WHEN user says 'reconstruct sessions', 'rebuild session notes', 'recover session notes', 'retroactively create notes', 'create notes from git history', 'notes are missing', 'backfill session notes', 'reconstruct what we did', OR /reconstruct.

### What This Skill Does

Reconstructs session notes for a PAI-registered project by reading:
1. Git commit history (authoritative record of what was built)
2. JSONL transcripts (user messages reveal intent, decisions, and context)

Generates one session note per day (or per logical session if multiple sessions existed in a day), numbered sequentially from the highest existing note number.

**ONLY include what can be verified from git log and JSONL. Never invent or embellish content.**

---

### Arguments

| Argument | Default | Description |
|----------|---------|-------------|
| `--days N` | 7 | Reconstruct notes for the last N days |
| `--since YYYY-MM-DD` | — | Reconstruct from this date forward |
| `--until YYYY-MM-DD` | today | Reconstruct up to this date |
| `--dry-run` | false | Show what would be created without writing files |
| `--commit` | false | Git commit the created notes after writing |

---

### Pre-Action Check

Before starting, verify:

1. **Project is registered**: Run `pai project detect` (or `pai project list`) to confirm the current project is known to PAI and get its Notes directory path.
2. **Notes directory exists**: The target directory should be `Notes/YYYY/MM/`. Create it if absent.
3. **Find highest existing note number**: Scan all `Notes/**/*.md` files for the pattern `^NNNN` to find max note number. New notes continue from there.
4. **NEVER overwrite existing notes**: If a note file already exists for that date/session, skip it and warn the user.

---

### Step 1 — Find JSONL Files

Claude Code encodes project paths lossily: `/`, spaces, dots, hyphens all become `-`. A project may have been accessed from multiple base directories (e.g., `~/Cloud/Development/PAI` and `~/dev/PAI` both encode to different paths).

**Search strategy — use glob patterns, not exact paths:**

```bash
# Find all encoded project directories that might match this project
ls ~/.claude/projects/ | grep -i "<project-slug-fragment>"

# For each candidate, look for JSONL files
ls ~/.claude/projects/<encoded-path>/*.jsonl 2>/dev/null

# Also check the dev copy if the project has one
# Example: if cwd is ~/dev/PAI, also check ~/Cloud/Development/PAI encoding
```

Collect ALL JSONL files from ALL matching encoded paths. A session may have been started from either location.

---

### Step 2 — Determine Time Range

Calculate the date range from arguments:
- `--days 7` → from (today - 7 days) to today
- `--since 2026-03-01` → from that date to today (or --until date)
- Default: last 7 days

---

### Step 3 — Extract Git History

For each day in the range:

```bash
git -C <project-dir> log \
  --after="YYYY-MM-DD 00:00:00" \
  --before="YYYY-MM-DD 23:59:59" \
  --format="%H|%ad|%s" \
  --date=short \
  --stat
```

Group commits by day. If no commits on a day, skip that day (no note to reconstruct).

Also capture:
- Files changed per commit (`--stat`)
- Author date (not committer date) for accurate day grouping

---

### Step 4 — Extract User Messages from JSONL

For each JSONL file, parse messages where `type == "user"` AND `message.role == "user"`:

```
Each line is a JSON object. Look for:
{
  "type": "user",
  "message": {
    "role": "user",
    "content": "..." | [{"type": "text", "text": "..."}]
  },
  "timestamp": "2026-03-15T10:23:45.000Z"
}
```

Filter messages by timestamp to match the day being reconstructed.

Extract:
- The text content of user messages (ignore tool_result entries)
- Timestamps for ordering
- Session ID (`sessionId` field) to group messages per session

**SKIP** messages that are:
- Tool results (`content` is array with `type: "tool_result"`)
- System-generated (very short single-word messages like "go", "continue")
- Pure confirmations ("yes", "ok", "sounds good")

**KEEP** messages that reveal:
- Intent ("build a feature that...", "I need X to do Y")
- Decisions ("let's use approach A instead of B")
- Architectural choices
- Problem descriptions
- Requirements changes

---

### Step 5 — Identify Logical Sessions

A "logical session" is a continuous work block. Use these signals to split a day into multiple sessions:
- Gap of more than 3 hours between messages
- Different JSONL session IDs with significant time gaps
- Commits with clearly different themes separated by time

If only one logical session exists for a day, create one note. If multiple exist, create one note per session with a suffix: `NNNN - YYYY-MM-DD - Title.md`, `NNNN+1 - YYYY-MM-DD - Title (2).md`.

---

### Step 6 — Generate Note Title

The note title comes from synthesizing git commits for that session:
- If commits share a theme: use that theme ("Implement vault indexer")
- If commits are varied: use the primary/largest change ("Refactor session notes + misc fixes")
- Use the conventional commit prefix if present: "feat: Add dark mode" → "Add Dark Mode"
- Title should be 3-7 words, title-case

---

### Step 7 — Write the Note

**Note filename format:** `NNNN - YYYY-MM-DD - Title.md`

**Path:** `Notes/YYYY/MM/NNNN - YYYY-MM-DD - Title.md`

**Content template:**

```markdown
# Session: [Title]

**Date:** YYYY-MM-DD
**Status:** Completed
**Reconstructed:** true (from JSONL + git history)

---

## Work Done

[Group related commits into logical sections by theme/component, not by commit order.
Each section describes WHAT was built and WHY, derived from commit messages and user messages.
Use present-tense descriptions: "Add X", "Fix Y", "Refactor Z".]

## Key Decisions

[Architectural choices, technology selections, approach changes.
ONLY include decisions that are explicitly stated in user messages or strongly implied by commit message changes (e.g., a series of "revert" commits followed by a new approach).
Format as bullet points.]

## Known Issues at End of Session

[Bugs discovered, things left unfinished.
Derive from: last commits in session (if they add TODOs or fix-me comments), user messages mentioning problems, or explicit "not done yet" statements.
Omit this section if nothing can be verified.]

---

**Tags:** #[project-slug] #reconstructed
```

**Filling rules:**
- Work Done: Always present (use commits as primary source)
- Key Decisions: Only if verifiable from user messages or commit patterns
- Known Issues: Only if verifiable; omit section entirely if nothing found
- Tags: Use the PAI project slug from `pai project detect`

---

### Step 8 — Output Summary

After writing (or dry-run preview):

```
Reconstructed N session notes:
  0042 - 2026-03-13 - Implement Reranker          → Notes/2026/03/
  0043 - 2026-03-14 - Add Recency Boost            → Notes/2026/03/
  0044 - 2026-03-15 - Zettelkasten Schema Update   → Notes/2026/03/

Skipped: 2026-03-12 (no commits)
Skipped: 2026-03-16 (note already exists: 0041 - 2026-03-16 - ...)
```

If `--commit` was passed:
```bash
git add Notes/
git commit -m "docs: reconstruct session notes for YYYY-MM-DD to YYYY-MM-DD"
```

---

### Anti-Defaults

- **NEVER overwrite existing notes.** Skip silently, report in summary.
- **NEVER invent content.** If a decision isn't in the JSONL or deducible from commits, leave it out.
- **NEVER fabricate commit messages.** Copy them verbatim from git log.
- **NEVER assume intent from assistant messages.** Only user messages reveal intent.
- **NEVER add speculation.** "It appears that..." or "likely..." should not appear in notes.
- **DO trim noise.** Skip trivial messages ("ok", "yes", "go") that add no signal.
- **DO handle missing JSONL gracefully.** If no JSONL files found, generate notes from git only — mark the "Key Decisions" section as "Not available (no JSONL transcript found)".

Versions

The database has no other skills named Reconstruct.

Database snapshot: 13.11.2026 · package version 9a89bb535b95 (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

  • 100okf-backfill-from-history
    OKF — Reconstruct an OKF bundle by event-sourcing a repository's history (git log and Claude session transcripts). Use when creating an `.okf/` bundle for an existing repository that predates this skill, or when resuming an interrupted backfill session. Triggers on: "reconstruct…
  • 90recall
    Reconstruct your recent working context from agent session history, legacy pi transcripts, and live git state, then hand back a tight current-state brief. Use for 'recall my work on X', 'catch me up', 'what have I been working on', 'where did I leave off', before starting or resuming work.
  • 100backfill
    Reconstruct an OKF bundle by event-sourcing a repository's history (git log and Claude session transcripts). Use when creating an `.okf/` bundle for an existing repository that predates this skill, or when resuming an interrupted backfill session. Triggers on: "reconstruct the…
  • 95git-notes
    Git笔记(git-notes)微笔记读写操作与产品咨询。当用户要求记一条笔记、查/搜/改/删自己的 git-notes 笔记、询问笔记内容(如"有哪些待办"、"我记过XX吗"、"最近记了什么")、询问 git-notes 产品本身(是什么/官网/开源/安装/远端同步/附件图片)、或提到"git笔记"、"记到笔记里"、"我的笔记"且本机装有 git-notes 时使用。所有读写必须通过 git-notes CLI 完成,禁止直接读取/grep/编辑 ~/.git-notes/ 下的任何笔记文件;CLI 未安装时先 npm install -g…
  • 90recall
    Reconstruct your recent working context from your own session history, live state, and the shared record (user reports, prior fixes, incidents), then hand back a tight current-state brief. Use for 'recall my work on X', 'catch me up', 'what have I been working on', 'where did I…
  • 90recall
    Reconstruct your recent working context from your own chat history, live state, and the shared record (user reports, prior fixes, incidents), then hand back a tight current-state brief. Use for 'recall my work on X', 'catch me up', 'what have I been working on', 'where did I…

Feedback and reports

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