Document heapy diff limitations

Heapy diff can yield both false positives
and false negatives due to keying on heap
pointers. This is difficult to fix, so
we're just documenting this for now.

Refs zombocom#31

Author: mttkay

README.md

@@ -47,6 +47,20 @@ Allocated STRING 9991 objects of size 399640/491264 (in bytes) at: scratch.rb:24
 Writing heap dump diff to output.json
 ```
 
+#### Limitations
+
+Due to how the garbage collector in MRI manages objects on the Ruby heap, `heapy diff` may produce incomplete
+or incorrect diffs under the following circumstances:
+
+1. **Heap compaction.** When compacting the Ruby heap either manually via `GC.compact` or with auto-compaction
+   enabled, heapy cannot produce accurate diffs, because objects may move into different heap slots and will appear as
+   newly allocated even if they weren't. In general, any mechanism that moves existing objects from one heap slot to
+   another will invalidate diff reports. Always turn off compaction before taking the `<after>` heap dump.
+1. **Temporary allocations.** Diffs might omit objects from an `<after>` dump if Ruby allocated them into heap slots that were
+   previously occupied by different objects in the `<before>` dump, and which were then deallocated between both dumps.
+   To minimize the chance of this happening, triggering a major GC three or more times between heap dumps can help
+   tenuring survivors and thus stabilizing the heap prior to taking a diff.
+
 ### Read a Heap Dump
 
 Step 1) Generate a heap dump. You could [do this manually](http://samsaffron.com/archive/2015/03/31/debugging-memory-leaks-in-ruby). Or you can use a tool like [derailed_benchmarks](https://github.com/schneems/derailed_benchmarks)