maintainer-docslisted

# maintainer-docs Some code reads as wrong precisely because the reason it is right does not fit in the code. A maintainer document preserves that reason where the next person will find it before simplifying the behaviour away This skill governs three repository-wide documents. It does not turn every explanation into documentation: the first question is always whether the reason has a natural line of code to live beside ## Where the explanation lives - **One line owns the reason:** write a short inline comment beside that line. State the non-obvious why, not what the line does - **Several places depend on the same reason, or no line owns it:** use one dedicated file at the repository root - **The subject is already owned by a focused document tree:** keep it there. `references/pitfalls.md` is an ordinary reference page, not a misplaced `PITFALLS.md` Do not copy the full explanation into both places. An inline comment may point to the root document, and the root document names every place it governs; one of them carries the reasoning and the others carry links ## Choose the document - **`WORKAROUNDS.md`:** code or configuration that exists only because an external defect or limitation leaves no cleaner route. The entry says what it prevents and how to decide that it can be removed - **`DEVIATIONS.md`:** an intentional departure from the obvious, default or documented route. The entry preserves the trade, the rejected alternative and the condition that would make the dec