Updating Without Starting Over

Understand Anything is meant to be a living map, not a report that becomes obsolete after the first commit. This chapter follows how the project decides what changed, what can be preserved, and when an incremental update is safe. The practical outcome is a way to read the graph's maintenance state: a fast update is useful only when it preserves the symbols and relationships that still exist and makes uncertainty visible when it cannot.

Content can change without graph structure changing

A file's bytes can change for many reasons. Someone may reformat it, revise a comment, improve an error message, or rewrite an internal implementation while keeping its public surface and relationships intact. Other edits add a function, remove a class, change a parameter, alter an import, or move a method to a different owner. Those changes have different consequences for a graph.

The project captures this distinction with per-file fingerprints. A fingerprint stores a content hash, but it also records the parts of a file that affect the graph: function names and ownership, parameters and return types where available, export status, class methods and properties, imports, exports, and line counts. It records whether a structural analysis was actually available. The content hash answers whether the file's bytes are identical. The structural fields help answer whether the graph-relevant shape is different.

The comparison has three meaningful outcomes. If the content hash is unchanged, the file is NONE and needs no update. If the content differs but the captured structural signatures still match, it is COSMETIC in the graph's vocabulary. That label is easy to misread. It does not mean the behavior is unimportant; an internal algorithm can change substantially while the graph sees no new function, class, import, export, or ownership relationship. It means the existing structural model has no detected reason to be rebuilt.

If a signature changes, a file is STRUCTURAL. New or removed functions, changed parameters or return types, changed exports or imports, class-method changes, and other graph-relevant differences can trigger that result. A file without structural analysis is also handled conservatively: a content change cannot prove that its structure stayed the same, so the system treats it as structural rather than granting a false cosmetic classification. The same caution applies when a callable's ownership is unresolved.

This is a deliberate division between graph maintenance and behavior analysis. The fingerprint is designed to capture what affects the stored knowledge graph, not every semantic difference in an implementation. It can prevent unnecessary reanalysis for an unchanged public shape, but it cannot tell a reader whether an error-handling change introduces a production bug. An incremental update preserves the map's structural assumptions; it is not a substitute for tests, review, or runtime observation.

Update scope is chosen by the shape of change

Once the project has classified changed files, the update classifier chooses how wide the recomputation should be. With no structural changes, the action is SKIP, even if files have cosmetic-only changes. With a small number of localized structural changes that do not alter the project's directory organization, the action is a partial update. The system can replace the affected files' nodes and relationships while retaining the rest of the graph.

A wider update is needed when the change affects the architecture's context. New or removed top-level directories can change how layers should be interpreted, so the classifier chooses an architecture update and reruns layer and tour work. A larger set of structural changes also crosses that boundary. If structural change becomes broad enough—more than the configured file-count or project-percentage threshold—the classifier recommends a full update. These thresholds are implementation rules for selecting work, not estimates of risk or code quality.

The reason for widening the scope is causal.