The docs for IBuildEngine3.Yield() and .Reacquire() describe how to call them and what happens but aren't very crisp on what burdens choosing to use them imposes on a task. We should extend them to describe:

• After calling Yield(), global process state like environment variables and current working directory can change arbitrarily until Reacquire() returns.
• As a result, if you are going to depend on any of that state, for instance by opening files by relative path rather than calling ITaskItem.GetMetadata("FullPath"), you must do so before calling Yield().
• The common pattern is to figure out what all the long-running work is and start it before yielding.