Notebook

Project trail system. Initialize, save, recover, migrate, and manage project notes.

When NOT to use this skill

No active project context (no git repo, no project root) — say so, don't create a floating notebook
User wants to summarize or extract knowledge from content — use
```
/extract
```
instead
Notes already exist and user just wants to read them — read directly with Read tool, skip the skill

Quick Reference

Proactive save rule: Save after every significant decision, failure, or constraint discovered — without being asked. Every ~20 tool calls without a save is too long. If you would say "I should remember this," write it now.

Command	Action
`/notebook`	Init (new project) or status (existing)
`/notebook save`	Write a note immediately — never prompts, just writes
`/notebook save resolved: <desc>`	Save a note and resolve the matching lesson
`/notebook recover`	Read index + lessons + flagged notes, summarize state
`/notebook migrate [path]`	Convert messy notes into notebook format

/notebook — Init & Status

If notebook/ doesn't exist (new project):

Locate project root — walk up from cwd looking for:

PROJECT_STATE.md

CLAUDE.md

.git/

package.json

Cargo.toml

pyproject.toml

go.mod

If no project root found: tell the user "No project root detected — create a project first."

Create:

notebook/
├── _index.md
└── lessons.md

Initialize

_index.md

markdown

# Notes Index

Project trail — read this first on context recovery.

Initialize

lessons.md

markdown

# Lessons

What not to do. Read this every session.

Add
```
notebook/
```
to
```
.gitignore
```
(process notes are AI working memory, not public docs)

Confirm:

Notebook initialized at {project_root}/notebook/
notebook/ added to .gitignore — remove to track in git.

Retroactive save — scan the current conversation for any decisions, failures, constraints, or learnings that have already occurred. Save each one as a note immediately. If the notebook is being initialized mid-session, there is almost certainly unsaved context. Do not wait to be asked.

If notebook/ already exists (status):

Read
```
_index.md
```
Read
```
lessons.md
```
Report: number of notes, number of lessons, last note date, count of ⚑-flagged notes
Show the last 5 index entries

/notebook save — Write a Note

Never prompt. Never ask questions. Just write.

Step 1: Locate Project Root

Walk up from cwd:

PROJECT_STATE.md

→

CLAUDE.md

→

.git/

→

package.json

Cargo.toml

pyproject.toml

go.mod

No root found → "No project root detected. Run

/notebook

from within a project first."

Step 2: Ensure Infrastructure

notebook/

doesn't exist, create it with

_index.md

and

lessons.md

silently.

Initialize

_index.md

markdown

# Notes Index

Project trail — read this first on context recovery.

Initialize

lessons.md

markdown

# Lessons

What not to do. Read this every session.

Add

notebook/

.gitignore

if not already present.

Step 3: Next Note Number

Read

_index.md

, find highest note number, increment. Start at

if empty.

Step 4: Infer Content

Priority order:

Explicit argument —

/notebook save constraint: RLS can't do cross-schema joins

Conversation context — if bare
```
/notebook save
```
, synthesize from recent exchanges
Both — user hint + contextual expansion

Step 5: Classify Type

Infer from content. Never ask.

Type	Signal
`decision`	Chose between options, committed to approach
`learning`	Non-obvious gotcha, unexpected behavior
`constraint`	Hard limitation (library, API, platform)
`pivot`	Changing direction from previous approach
`investigation`	Research findings, benchmarks, comparisons
`failure`	Tried something, didn't work — and why
`resolved`	A previous lesson/constraint no longer applies

Default:

learning

Step 6: Write the Note

File:

notebook/NNNN-type-short-title.md

Quick format (default):

markdown

# NNNN: Short Descriptive Title

**Type:** type | **Date:** YYYY-MM-DD

Content. 1-5 lines. Be specific — library names, error messages, version numbers.
What happened, what it means going forward.

Full format (major architectural decisions only):

markdown

# NNNN: Short Descriptive Title

**Type:** decision | **Date:** YYYY-MM-DD
**Status:** accepted

## Context
What prompted this? (1-3 sentences)

## Decision
What we decided. Be specific.

## Rationale
Why this over alternatives.

## Alternatives Considered
- **Alternative A:** Rejected because X

## Consequences
What this means going forward.

Threshold: meaningful alternatives considered AND hard to reverse → full format. Everything else → quick.

Step 7: Update Index

Append a rich one-line summary to

_index.md

- NNNN type: Detailed one-liner useful standalone

⚑ flag for critical constraints, breaking discoveries, architectural decisions:

- NNNN ⚑ constraint: Critical thing every session must know

Step 8: Update Lessons (conditional)

For types
failure
,
learning
,
constraint
: append a distilled one-liner to

lessons.md

Format — pure signal, no metadata:

- Concise lesson. What not to do and why, or what to do instead.

The full note has context and details. The lesson is the takeaway — one line a model can scan in a second.

For type
resolved
: write the note as usual, then find the matching lesson in

lessons.md

and strike it:

- ~~Prisma doesn't work with edge runtime~~ → Resolved in 0047

How to match: use the content of the

/notebook save resolved:

argument to find the most relevant lesson line. Match on key terms (library names, error descriptions, the constraint being resolved). If no clear match is found, write the note but warn:

Note saved but no matching lesson found to resolve.

Strikethrough preserves history — a model sees what used to be a problem and knows to skip it. The note reference lets anyone find the resolution details.

Step 9: Update PROJECT_STATE.md (conditional)

Only if the note materially changes project state (blocking constraint, architecture change, pivot). If no

PROJECT_STATE.md

exists, skip.

Output

Single line confirmation:

Saved: notebook/NNNN-type-short-title.md

Nothing else.

/notebook recover

Read full
```
_index.md
```
Read full
```
lessons.md
```
Open all ⚑-flagged notes
Open the last 3 notes
Read
```
PROJECT_STATE.md
```
if it exists
Summarize: what the project is, key decisions, active constraints, known pitfalls, current state
Ask: "What's changed since this was last updated?"

/notebook migrate

Convert existing messy notes into notebook format. One-time onboarding for projects with pre-existing notes.

Scan the target folder (cwd or specified path) for markdown and text files
Read each file
Classify each: decision, learning, constraint, failure, investigation, or pivot
Write each as a properly numbered notebook note in
```
notebook/
```
Build
```
_index.md
```
from scratch with rich one-line summaries
Extract lessons from anything that looks like a failure, constraint, or learning → populate
```
lessons.md
```
Leave originals untouched. User deletes them when satisfied.

notebook/

already has notes, continue numbering from the highest existing. Migrate never overwrites existing notes.

After migration, report: how many files found, how many converted, how many lessons extracted. Show the generated index.

Resolving Lessons

To mark a lesson as resolved use:

/notebook save resolved: <exact phrase or lesson number>

Matching rules:

Prefer exact phrase match from lessons.md
If ambiguous or no match found, list the open lessons and ask the user to confirm which one
Never silently skip — always confirm what was resolved

Mark resolved lessons with strikethrough in

lessons.md

markdown

~~Lesson text here~~ *(resolved: [date or brief reason])*

Archiving: When

lessons.md

exceeds 50 resolved (struck-through) entries, move all resolved lessons to

lessons-archive-YYYY-MM.md

and remove them from the active file. Keep only open lessons in the active file.

Stale Lesson Detection

When reading

lessons.md

during context recovery, check if any lessons are outdated — library upgrades, removed constraints, resolved workarounds. Flag to the user: "Lesson [X] may be stale — [reason]. Want me to resolve it?"

Context Recovery Priority

On any new session or

/notebook recover

, read in this order:

```
_index.md
```
— what is this project, what happened
```
lessons.md
```
— what not to do
⚑-flagged notes — critical details the index can't capture
Last 3 notes — recent context
```
PROJECT_STATE.md
```
— current snapshot (if exists)

Rules

Never prompt on /notebook save. Infer everything from context and arguments.
Quick format by default. Full format is rare — major architectural decisions only.
Rich index entries. The index alone should be sufficient for context recovery.
Be specific. Library names, error messages, versions > vague descriptions.
Failures are gold. "Tried X, failed because Y" prevents loops. Always save these.
One note per save. Don't batch multiple insights.
⚑ sparingly. Only for things every future session must read.
Notes are append-only. New moment = new note. Update existing only to mark superseded.
Lessons are distilled. One line, pure signal. If you need context, open the note.

notebook

NPX Install

Tags

SKILL.md Content

Notebook

When NOT to use this skill

Quick Reference

/notebook — Init & Status

If notebook/ doesn't exist (new project):

If notebook/ already exists (status):

/notebook save — Write a Note

Step 1: Locate Project Root

Step 2: Ensure Infrastructure

Step 3: Next Note Number

Step 4: Infer Content

Step 5: Classify Type

Step 6: Write the Note

Step 7: Update Index

Step 8: Update Lessons (conditional)

Step 9: Update PROJECT_STATE.md (conditional)

Output

/notebook recover

/notebook migrate

Resolving Lessons

Stale Lesson Detection

Context Recovery Priority

Rules