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