/postmortem, /wrong, /learn: Turning Every Bug Into a Permanent Memory File | AI PM Portfolio

/postmortem, /wrong, /learn: Turning Every Bug Into a Permanent Memory File

April 11, 2026 · 9 min read · Claude Code

Last Updated: 2026-04-11

Claude Code custom slash commands called skills can create permanent memory files that persist across sessions. Three skills -- /postmortem, /wrong, and /learn -- capture production bugs, incorrect AI suggestions, and daily lessons as structured markdown in ~/.claude/projects/memory/. After two months of use, this system produced 50+ memory files that eliminated repeated mistakes and gave every new session full context of past incidents.

Why does your AI coding assistant forget everything between sessions?

You fix a production bug at 11 PM. You understand exactly what broke, why it broke, and the subtle pattern that caused it. By next week, the details have faded. By next month, you hit the same class of bug and spend another two hours rediscovering what you already learned.

AI coding assistants make this worse. Claude Code, Cursor, GitHub Copilot -- they all start every session with a blank slate. No memory of yesterday's incident. No knowledge of which approaches failed last time. No awareness that the same Supabase RLS pattern has tripped you up three times this quarter.

According to Anthropic's Claude Code documentation, the memory system uses markdown files with YAML frontmatter stored in project-specific directories. Claude reads these files at conversation start, giving it persistent context across sessions. But the documentation describes the mechanism -- it does not describe a system for systematically capturing engineering knowledge. That system is what I built.

Over two months, I created three Claude Code custom slash commands (called "skills") that turn every bug, mistake, and lesson into a permanent, indexed memory file. The result: 50+ memory files, zero repeated errors from previously documented incidents, and new sessions that start with full context of past failures. I covered the broader skill system in my Claude Code operating system post.

What are the three skills and how do they work?

Each skill is a markdown file in ~/.claude/skills/ with YAML frontmatter (name, description, allowed tools) and instructions that Claude follows when you invoke the command. The three knowledge-capture skills serve distinct purposes.

How does /postmortem capture production bugs?

After fixing any production bug, running /postmortem triggers a structured capture. Claude asks for the incident details (or infers them from the current session context) and writes a memory file with four sections: what broke, why it broke, the fix, and the pattern to watch for.

# Example: running /postmortem after a bug fix

$ claude
> /postmortem

# Claude generates this file automatically:
# ~/.claude/projects/-Users-you-yourproject/memory/project_email_dedup_fix.md

---
name: Email Deduplication Race Condition
description: Duplicate emails sent when email_log write fails silently.
  The dedup check queries email_log, but if the initial SEND never wrote
  to email_log, the dedup check passes every time.
type: project
---

## What broke
Users received 13 duplicate "documents received" emails in 2 minutes.

## Why
The email send function called Resend but did not await the email_log
insert. The Vercel serverless container terminated before the log write
completed. Every subsequent trigger found zero log entries and sent again.

## The fix
Awaited the email_log insert before returning from the send function.
Added a unique constraint on (user_id, email_type, document_id) as a
database-level safety net.

## Pattern to watch for
Any fire-and-forget async operation in a serverless environment.
Vercel kills the container after the response is sent. If your side
effect is not awaited, it will be dropped silently.

That pattern -- "fire-and-forget in serverless" -- appeared in three separate bugs across two weeks in my codebase. The first postmortem documented it. The second time, Claude flagged the pattern before I even finished describing the symptoms because it had read the memory file at session start. The third time, I caught it during code review because the pattern was now part of my mental model.

How does /wrong build a library of AI mistakes?

When Claude gives incorrect advice and you discover the real fix was different, running /wrong documents the gap. This is not about blame -- it is about calibrating trust. After 30+ wrong entries, clear patterns emerged: Claude was consistently unreliable on Supabase RLS edge cases (5 wrongs), Vercel serverless timing (4 wrongs), and Stripe webhook idempotency (3 wrongs).

# Example: running /wrong after discovering Claude's suggestion was incorrect

$ claude
> /wrong

# Claude generates:
# ~/.claude/projects/-Users-you-yourproject/memory/feedback_rls_fk_triggers.md

---
name: RLS + Foreign Key Trigger Gotcha
description: SECURITY DEFINER needed on triggers that cross RLS boundaries.
  FK SET NULL requires UPDATE policy on the referencing table.
type: feedback
---

## What Claude suggested
Drop the foreign key constraint and handle cascading deletes in
application code.

## What the real fix was
Keep the FK constraint. Add SECURITY DEFINER to the trigger function
so it executes with owner privileges, bypassing RLS. Add an explicit
UPDATE policy for the SET NULL operation.

## Domain
Supabase RLS / PostgreSQL triggers

## Lesson
Claude defaults to "remove the constraint" when the real answer is
"understand the security model." Always check whether a SECURITY
DEFINER or explicit policy solves the problem before removing
database-level guarantees.

The compound effect is significant. After documenting 5 RLS-related wrongs, Claude now prefaces its Supabase RLS suggestions with a caveat: "I have been wrong about RLS edge cases before -- verify this against your existing policies." That self-awareness did not exist in session one. It emerged from the accumulated wrong entries.

How does /learn turn history into daily lessons?

The /learn skill is a 5-minute daily lesson. It pulls from two sources: the postmortem and wrong history (real incidents from your codebase) and core engineering concepts that connect to those incidents. Each lesson uses a real example from your project, not a generic tutorial.

# Example: a /learn session

$ claude
> /learn

# Claude picks a topic based on recent postmortems:
"Your last 3 postmortems all involve async operations in serverless.
Today's lesson: the JavaScript event loop in serverless containers.

In a traditional Node.js server, the event loop runs indefinitely.
Pending async operations (setTimeout, unresolved Promises, open
database connections) keep the process alive.

In serverless (Vercel, AWS Lambda), the container freezes or
terminates after the response is sent. Any unresolved Promise
at that point is silently dropped.

Here is the pattern from your codebase:
[shows actual code from the project with the anti-pattern highlighted]

The fix: always await side effects before returning the response,
or route them through a durable execution engine like Inngest.

Quiz: In your confirm route, there is a fetch() call to the
extraction endpoint. Is it awaited? What happens if it is not?"

The lesson pulls directly from the codebase. It references real files, real incidents, and asks questions that test comprehension. Over 60 days, these 5-minute sessions covered topics I would not have studied on my own: PostgreSQL trigger execution order, Stripe webhook retry semantics, Next.js middleware vs proxy patterns, and the difference between Promise.race and Promise.allSettled for timeout guards.

How does the memory file system actually work?

Claude Code's memory system has three layers, each serving a different scope.

1. CLAUDE.md -- a single file in the project root with high-level rules and conventions. Good for "always use TypeScript strict mode" but too coarse for incident-specific knowledge.
2. Memory files -- individual markdown files in ~/.claude/projects/{project-path}/memory/, each with YAML frontmatter. Claude reads all of these at session start. This is where postmortem, wrong, and learn outputs live.
3. An index file (MEMORY.md) -- a master file in the memory directory that lists and categorizes every memory file with one-line descriptions. This makes the collection discoverable and navigable.

The naming convention encodes the type: project_* for postmortems and project state, feedback_* for wrongs and corrections, reference_* for stable reference data. Claude uses these prefixes to prioritize relevance when context windows get large.

Scaling note: At 50+ memory files, the total token count at session start is approximately 15,000-20,000 tokens. Claude Code's context window (200K tokens) handles this comfortably. At 200+ files, you would want to implement a relevance filter or split into sub-projects. I have not hit that limit yet.

How do memory files compare to other knowledge preservation methods?

The critical differentiator is row two: "AI-readable at start." Memory files are the only method where Claude has the knowledge before you ask for it. Git commits require a query. Notion requires copy-pasting. Code comments require opening the right file. Memory files are ambient context -- always present, always available. This connects to the broader skill architecture I described in my skills deep-dive.

What does the enforcement system look like?

Creating the skills is step one. Actually using them consistently is step two, and it is harder. I built an enforcement layer -- a memory file that instructs Claude to prompt me at specific moments:

• After fixing a bug: Claude says "Bug fixed. Run /postmortem now -- 2 minutes while it is fresh."
• After being corrected: Claude says "I was wrong on that one. /wrong to log it -- helps me get better for you."
• Once per session: Claude nudges "Have you run /learn today?" -- once, not nagging.
• If I skip it: Claude reminds once: "You just fixed a bug without capturing the lesson. /postmortem takes 60 seconds." Then respects my choice.

This enforcement file (feedback_skill_enforcement.md) is itself a memory file. It gets loaded at session start just like every other memory. The system enforces itself. In my experience, the enforcement nudges increased my postmortem completion rate from roughly 30% (when relying on discipline alone) to over 90%.

What is the compound effect after two months?

After 60 days of consistent use across a production codebase with 189 API routes, 65+ database tables, and 206 modules:

• 52 memory files created (28 postmortems, 16 wrongs, 8 learn summaries)
• 3 bug categories eliminated -- fire-and-forget async, RLS policy gaps, and Stripe webhook race conditions stopped recurring after being documented
• New session ramp-up dropped from ~10 minutes to ~2 minutes -- Claude starts with full context of past incidents, architecture decisions, and known pitfalls
• Domain-specific trust calibration -- I now know exactly where Claude is reliable (TypeScript refactoring, React component structure) and where to double-check (RLS policies, serverless timing, webhook idempotency)

The meta-lesson is this: the best engineers are not the ones who never make mistakes. They are the ones who never make the same mistake twice. These three skills automate that discipline. Every bug becomes a permanent lesson. Every AI mistake becomes a calibration data point. Every daily learn session compounds into a broader pattern library.

The system does not require exceptional discipline. It requires three markdown files in a skills directory and a willingness to spend 60 seconds after each incident. The AI handles the rest -- the structured capture, the indexing, the retrieval at session start, and the enforcement nudges that keep you honest.

Frequently Asked Questions

How do you create a custom slash command in Claude Code?

Create a markdown file in ~/.claude/skills/ (global) or .claude/skills/ (project-level) with YAML frontmatter containing name, description, and allowed-tools. The file body contains the instructions Claude follows when you type the command. Claude Code discovers these files automatically -- no restart or configuration needed.

Do memory files slow down Claude Code sessions?

At 50 files totaling approximately 18,000 tokens, there is no perceptible slowdown. Claude Code's 200K context window absorbs this easily. You would need 500+ large memory files before context pressure becomes a concern. At that scale, splitting into sub-projects or archiving resolved postmortems is the practical solution.

Can this system work with other AI coding assistants like Cursor or Copilot?

The concept transfers but the mechanism differs. Cursor supports .cursorrules files for persistent context. GitHub Copilot uses .github/copilot-instructions.md. Neither has the structured skill invocation that Claude Code provides, so you would need to manually create the memory files. The core insight -- capturing incidents as structured, AI-readable files -- is tool-agnostic.

What is the difference between a memory file and CLAUDE.md?

CLAUDE.md is a single file for project-wide rules ("always use strict TypeScript," "never raw-fetch Supabase Storage"). Memory files are individual documents for specific incidents, patterns, and corrections. CLAUDE.md is your constitution. Memory files are your case law. Both are loaded at session start, but memory files scale to hundreds of entries while CLAUDE.md should stay under 200 lines.

How do you prevent memory files from becoming stale or contradictory?

Each memory file has a timestamp and originSessionId in its frontmatter. Claude Code adds a system reminder noting the file's age when loading it. For actively evolving areas, I update the existing memory file rather than creating a new one. The weekly /weekly-review skill audits recent memories and flags any that contradict each other or reference deprecated patterns.

Dinesh Challa is an AI Product Manager building production software with Claude Code. Follow him on LinkedIn.

Published April 11, 2026. Part of a series on building a complete Claude Code operating system with 20 agents, 8 skills, and 11 hooks.