A decision and its reasons
What makes a decision understandable to someone taking over
Writing “the system only prepares drafts” describes a behaviour. Adding “because some answers commit the client to a course of action and require a responsible person's decision” explains the choice. Stating “automatic sending has not been tested or authorised” prevents a future possibility from being mistaken for a delivered function.
Different people need this information. The user understands when to stop; the maintainer recognises which change would alter the scope; the person commissioning the work can distinguish a defect from a new request. You do not need to hand over every project conversation. You need to preserve the connections without which a decision would become arbitrary.
Illustrative case
An example: answering from product documentation
Consider an entirely illustrative case, not a MAIOS client or a measured result. A team wants to prepare technical answers from manuals and release notes. The proposed solution produces a draft with the documents used; a person checks it and decides whether to send it.
In the first trial, an answer is correct for the previous product version but wrong for the version requested. Replacing that sentence fixes the case. Understanding that the connection between the question and the version was missing suggests a reusable correction instead: identify the version before selecting sources, and ask for clarification when that information is absent.
This difference matters at handover. The new maintainer receives not just a corrected answer, but the reason why source selection needs to work that way. The correction can inform the next relevant case without becoming an indiscriminate rule for every other project.
A practical starting point
A worked handover note
You can start with the following note and adapt it to your work. Its entries belong to the example; they are not universal requirements.
Requested outcome
Help support staff prepare answers consistent with the product version specified in the request.
Decision and reason
Produce a draft with sources; a person decides whether to send it because they must assess the commitment made in the answer.
Sources and dependencies
Manuals and notes approved by the product owner, associated with their version. Ask for clarification if the version is missing.
Correction retained
An answer used outdated documentation: source selection must follow the version in the request, not just similarity between words.
State and boundary
The answer in the example has been corrected; checking new requests remains to be done. Sending and account changes are excluded.
When to reopen the decision
The sources, requested outcome or actions the system is expected to take change. Identify which decisions depend on that change.
Continuation
Try a request about another version; observe which sources are selected and how ambiguity is handled.
A test to carry out
Hand the note to a colleague
Try giving this note to a colleague together with the necessary materials. Ask them to explain the decision and handle a variation of the case without reusing the same answer. If they still need to reconstruct every step with you, you have identified a missing connection in the handover. This is a test to carry out, not an outcome already demonstrated by the example.
The present changes
Resuming work does not mean repeating the old solution
If only the person changes, recovering the reasons and sources behind the decision may be enough. If a source changes, identify which conclusions depended on it. If the client asks for a different outcome, you may need to reframe the problem and bring in other expertise.
In the example, “make the version clearer” and “send answers automatically” are not equivalent adjustments. The first request may concern how the output is understood. The second changes the system's effects and responsibilities. Treating both as small interface changes would hide the work actually needed.
This way of resuming a project keeps what has been learned usable, without forcing every new situation into the previous decision.
Learning from the work
From correcting a case to developing competence
A correction becomes useful beyond a single output when it changes how relevant cases are approached. To preserve it, record what made it necessary, which criterion changes and where that criterion applies. If you are correcting an isolated piece of information, updating the source may be enough: not every error needs a new procedure.
A lack of improvement is informative too. If the note is correct but the person taking over still cannot understand, the problem could lie in the explanation, access to materials or knowledge of the work. Adding more documentation without distinguishing these possibilities may leave the problem untouched.
Where this guide comes from
The connection with the work behind MAIOS
In the kernel through which we develop MAIOS, context, competences, results and correction are connected: what emerges from the work can change how the system approaches the next step. Reentry recovers the meaning of the path taken and considers it in the present context; it is not simply retrieving an earlier text.
We used this relationship to understand project handover. The guide's note makes part of it usable even in a team working without AI. The note is not, by itself, a kernel, and it does not demonstrate that an installed package will learn automatically or that the handover will succeed.
For more about the distinct product implementation, see MAIOS Project Kernel. The outcome here is narrower: being able to continue the work while understanding which reasons to preserve, which assumptions to reconsider and which capability is missing.
Frequently asked questions
Questions about project handover
What should accompany the code and instructions?
The reasons behind decisions, the sources they depend on, what has been checked and the conditions that call for reconsidering the work. The worked note in this guide provides an example to adapt.
Does the handover note prove that the system works?
No. It preserves the reasoning but does not replace testing. In the example, checking new requests remains to be done; the test with a colleague is proposed, not already observed.
Should every error become a new rule?
No. An isolated error may only need a source correction. A reusable criterion must retain the reason for the correction and the scope in which it is relevant.