exp-book

name	exp-book
description	Use when starting debug tasks, fixing bugs, building new features, performance optimization, dependency migration, or automated testing. Also use after completing significant problem-solving sessions involving undocumented behavior, repeated failed attempts, or multi-step debugging.

Exp-book

A searchable library of reusable team development experience.

When to Use

Before a task: Search for past solutions to avoid repeating known pitfalls.

After a task: Create a scroll only when the experience has reuse value — meaning a team member in a similar scenario would save significant time by reading it.

Write if any apply:

• Took wrong turns or multiple attempts before finding the correct approach
• Involved undocumented behavior, traps, or counter-intuitive decisions
• Established a reusable automation workflow or standard operating procedure

Do NOT write if:

• The solution is standard and well-documented (official docs cover it clearly)
• The experience is one-off project configuration with no transferable insight
• The insight is already captured in an existing scroll — update or supplement that scroll instead of creating a new one

Steps

Entry point:

• Triggered by CLAUDE.md (task just completed) → go directly to Write mode
• Triggered by user or task description (before task begins) → run Recall mode

---

Recall Mode (before task)

Step 1 - Locate the scrolls directory

Scrolls live in the references/ directory next to this SKILL.md. If the directory is missing or empty, silently begin the task.

Step 2 - Extract search keywords

Extract 3–5 keywords from the task description, prioritized by:

1. Error messages or error codes (most precise)
2. Specific tech names: library, API, tool, framework names
3. Problem patterns: e.g. "reconnect", "timeout", "CORS", "migration"

Avoid generic words like "fix", "bug", "error", "issue".

Step 3 - grep search

Resolve the references/ directory to its absolute path (sibling of this SKILL.md).

Use the Grep tool to search. Run one search per keyword. Deduplicate and merge results. Show at most 3 files, ranked by number of keyword hits; break ties by filename relevance to the task.

If zero hits on all keywords, try one broader synonym round before giving up.

Step 4 - Present results

On hits, read each file and output:

📚 Exp-book matches (N)

📖 {filename}
💡 Suggestion: {specific, actionable advice for the current task}

Keep the suggestion concise — extract only the parts relevant to the current task, not the full scroll content.

On no hits: silently begin the task, no message.

---

Write Mode (after task)

Step 1 - Generate filename

Lowercase English, hyphen-separated, describing the core problem:

• Good: react-hooks-dependency-trap.md
• Good: nextjs-image-cdn-cors.md
• Bad: bug-fix.md (too vague)

Step 2 - Distill content

Write it as a note for the next Claude session that hits the same scenario. Optimize for machine readability in context — the scroll will be injected into a future conversation as reference.

Length target: 30–80 lines. If longer, cut background and keep conclusions.

Principles:

• Lead with the conclusion — what to do, how to do it. Background is secondary.
• Minimize "why" — only include enough context to know when this scroll applies. Skip the debugging journey.
• Be specific — exact commands, exact code patterns, exact config. Vague advice has no reuse value.
• Include anti-patterns — "don't do X" is as valuable as "do Y".

No fixed structure. A scroll might be a bug fix, a workflow, a code pattern, a process, or a correction to a bad habit.

Step 3 - Check for existing scrolls

Before writing, grep references/ for the core topic. If a related scroll already exists, update it (add new insights, anti-patterns, or scenarios) rather than creating a duplicate.

Step 4 - Write the file

Use the Glob tool to find the absolute path of this SKILL.md. Write the scroll to the sibling references/{filename}.md.

Then notify the user:

✅ Scroll saved: references/{filename}.md

Or if updating:

✅ Scroll updated: references/{filename}.md