Lessons Learned
Patterns, mistakes, and decisions extracted from real project work. Each lesson is standalone and designed to be useful on any project.
28Lessons
5Categories
Lesson 01
Data
XML to JSON Migration
Why and how to migrate a live data format without breaking consumers
Lesson 02
Data
Schema Enforcement at the Data Layer
Adding JSON Schema validation to catch data defects before they reach the UI
Lesson 03
Data
Content Quality Auditing at Scale
Measuring and enforcing quality thresholds across 1,650+ questions
Lesson 04
Data
Answer Position Bias
Why correct answers cluster in certain positions and how randomization fixes it
Lesson 05
Data
Hint Quality as a Spectrum
Designing a three-tier progressive hint system with measurable quality thresholds
Lesson 06
Data
AI-Graded Content Validation
Using LLMs to independently verify answer correctness across a large question bank
Lesson 07
Data
Verbatim Answer Leakage in Hints
How hints can accidentally give away answers, and systematic detection
Lesson 08
Architecture
Provider-Agnostic Plugin Architecture
Scaling from 1 to 10 providers without provider-specific code
Lesson 09
Architecture
Design System Migration
Introducing a token-based design system into an existing multi-page static site
Lesson 10
Architecture
Static Site as Application Platform
Building a full application with vanilla HTML/CSS/JS, no framework, no build step
Lesson 11
Architecture
Client-Side State with localStorage
Patterns for save/resume/history in a zero-backend architecture
Lesson 12
Architecture
Content Security Policy for Static Sites
Adding CSP to a no-build static site that uses ES modules and CDN imports
Lesson 13
Process
Code Review Driven Remediation
Turning a whole-codebase review into a phased, trackable remediation plan
Lesson 14
Process
Phased Release Planning
Breaking large features into independently shippable phases with explicit state tracking
Lesson 15
Process
Design-First Development
Writing design docs and PDRs before code, and when it pays off
Lesson 16
Process
Scaling Content Without Scaling Complexity
Adding 50+ exams across 10 providers while keeping the codebase stable
Lesson 17
Process
XSS in Trusted-Data Applications
Why innerHTML from "your own" data is still a vulnerability
Lesson 18
Testing
Equivalence Testing During Format Migration
Running 5,101 render-equivalence tests to prove JSON matches XML output
Lesson 19
Testing
Integration Testing with jsdom
Testing a browser application end-to-end without a browser
Lesson 20
Testing
Testing Provider Detection Logic
How a copied test diverged from production code, and the fix
Lesson 21
Engineering
XML Entity Encoding Pitfalls
The Q&A vs Q&A class of bugs in content pipelines
Lesson 22
Engineering
Schema Variant Consolidation
When parallel authoring produces incompatible schemas, and how to reconcile them
Lesson 23
Engineering
Bulk Metadata Enrichment Scripts
Writing Python tooling to patch thousands of elements programmatically
Lesson 24
Process
Lessons Learned as a Practice
Turning project experience into a durable, reusable knowledge base
Lesson 25
Process
Legacy Artifact Removal
Safely deleting dead code after a migration: dependency mapping, bulk deletion, verification
Lesson 26
Process
Building a Lessons Skill
Anatomy of a Claude Code skill file: frontmatter, mode dispatch, quality contracts, and hard rules
Lesson 27
Process
Building a Review Skill
Encoding a 7-category review checklist into a repeatable skill with evidence and phased remediation
Lesson 28
Process
Building a Phase Execution Skill
Automating plan execution with restart-safe state, verification gates, and atomic commits