lessons-learned

Lessons Learned

Iron Law

NO PHASE SHIPS WITHOUT LESSON CAPTURE

No exceptions:

• Not for "small phases" or "just a bugfix"
• Not for "we're in a hurry"
• Not for "nothing notable happened"
• Even smooth phases confirm what's working — capture it

When to Use

• After phase completion during /shipyard:ship (Step 3a)
• When reflecting on completed work to extract reusable knowledge
• When a build summary contains notable discoveries worth preserving

Natural Language Triggers

• "what did we learn", "capture lessons", "retrospective", "lessons learned"

When NOT to Use

• Mid-implementation (wait until the phase ships — partial lessons lack full context)
• Documenting code design decisions (put those in inline comments or architecture docs)
• Tracking active bugs (use issue tracker; lessons capture completed learning, not open problems)

Timing Rule

Run immediately after ship, before the next phase starts. Lessons captured 24+ hours later lose the "why" behind decisions. If you're about to start the next phase, capture lessons first.

Overview

The lessons-learned system captures discoveries, patterns, and pitfalls found during implementation and feeds them back into the project. Lessons are stored in .shipyard/LESSONS.md and optionally surfaced in CLAUDE.md so future agents benefit from past experience.

LESSONS.md Format

Store lessons in .shipyard/LESSONS.md using this exact structure:

# Shipyard Lessons Learned

## [YYYY-MM-DD] Phase N: {Phase Name}

### What Went Well
- {Bullet point}

### Surprises / Discoveries
- {Pattern discovered}

### Pitfalls to Avoid
- {Anti-pattern encountered}

### Process Improvements
- {Workflow enhancement}

---

New entries are prepended after the # Shipyard Lessons Learned heading so the most recent phase appears first. Each phase gets its own dated section with all four subsections.