diff --git a/cabal-install/Distribution/Client/Install.hs b/cabal-install/Distribution/Client/Install.hs
index bdc8cd7495e19d144ea6f7d0b1d89a8a27b9e895..69083afb9560012854d1b2f54dbbeae02d681cbf 100644
--- a/cabal-install/Distribution/Client/Install.hs
+++ b/cabal-install/Distribution/Client/Install.hs
@@ -561,12 +561,12 @@ packageStatus _comp installedPkgIndex cpkg =
     changes :: Installed.InstalledPackageInfo
             -> ReadyPackage
             -> [MergeResult PackageIdentifier PackageIdentifier]
-    changes pkg pkg' =
-      filter changed
-      $ mergeBy (comparing packageName)
-          (resolveInstalledIds $ Installed.depends pkg)
-          (resolveInstalledIds $ depends $ pkg')
+    changes pkg pkg' = filter changed $
+      mergeBy (comparing packageName)
+        (resolveInstalledIds $ Installed.depends pkg) -- deps of installed pkg
+        (resolveInstalledIds $ depends $ pkg')        -- deps of configured pkg
 
+    -- convert to source pkg ids via index
     resolveInstalledIds :: [InstalledPackageId] -> [PackageIdentifier]
     resolveInstalledIds =
         nub
diff --git a/cabal-install/Distribution/Client/InstallPlan.hs b/cabal-install/Distribution/Client/InstallPlan.hs
index 0505fbeaea94b677a818af5e79c1f2cd9fc07b2e..e750b12ac9ab1a24c2ec8a92d2ae6671f5aebafc 100644
--- a/cabal-install/Distribution/Client/InstallPlan.hs
+++ b/cabal-install/Distribution/Client/InstallPlan.hs
@@ -143,6 +143,17 @@ type PlanIndex = PackageIndex PlanPackage
 -- have problems with inconsistent dependencies.
 -- On the other hand it is true that every closed sub plan is valid.
 
+-- | Packages in an install plan
+--
+-- NOTE: 'ConfiguredPackage', 'ReadyPackage' and 'PlanPackage' intentionally
+-- have no 'PackageInstalled' instance. `This is important: PackageInstalled
+-- returns only library dependencies, but for package that aren't yet installed
+-- we know many more kinds of dependencies (setup dependencies, exe, test-suite,
+-- benchmark, ..). Any functions that operate on dependencies in cabal-install
+-- should consider what to do with these dependencies; if we give a
+-- 'PackageInstalled' instance it would be too easy to get this wrong (and,
+-- for instance, call graph traversal functions from Cabal rather than from
+-- cabal-install). Instead, see 'PackageFixedDeps'.
 data PlanPackage = PreExisting InstalledPackage
                  | Configured  ConfiguredPackage
                  | Processing  ReadyPackage
@@ -239,8 +250,6 @@ new platform cinfo index =
           }
       where (graph, vertexToPkgId, pkgIdToVertex) =
               PlanIndex.dependencyGraph fakeMap index
-              -- NB: doesn't need to know planFakeMap because the
-              -- fakemap is empty at this point.
             noSuchPkgId = internalError "package is not in the graph"
     probs -> Left probs