Emuni engineer 後藤勇人 turns an AI-refactor rollback into doc-first review rules

The starting point is a concrete failure: changes were split across several pull requests, and once integrated, behavior shifted in areas that were supposed to stay put. Goto judged the blast radius wide enough that reverting and restarting from specification cleanup was better than iterating on fixes. His diagnosis is that neither the feature he wanted to change nor the behavior he wanted to keep was traceable within the implementation diff, and that a regression test rewritten to match the new implementation can pass while no longer protecting the old behavior.

The rebuild moves the traceability upstream. Specifications are written out from the existing implementation, with a glossary fixing what business terms mean, and each kind of detail is assigned a single home document so a change does not require editing the same specification in several places. Requirements and requirements-as-conditions are kept as separate documents, and if a PBI or issue already carries purpose, scope, acceptance conditions and behaviors to preserve, that is used directly rather than duplicated.

The two skills encode the routine. maintain-design-docs separates pre-implementation design work from post-implementation reconciliation, classifies each candidate document as needing update, conditional or review-only, and requires a stated reason for documents left untouched, so a reader can tell "checked and unchanged" from "not yet looked at." add-function-comments limits edits to comments and docstrings, checking responsibilities, arguments, return values, exceptions and side effects against callers and tests. Goto notes that comments matching code still cannot by themselves prove a change was intended, which is why he reads the before-and-after design and code himself, including spots AI review did not flag.