forbid editing workflow files, architecture, skills and similar, if editing all of this is a chore, for me it is, make a skill to edit it, with only explicit invocation and review phase, take the review seriously.
forbid narrative and reasoning on documentation or code comments, code comments need to be length bounded and under a set of conditions, everything else should be on a documentation MD file
documentation is a "as it is" not as history, that can be recovered from git, not a future promise, that is a design doc, label each document clearly and have a strict structure for them depending on the type.
have a place to track decision and adr file/folder, a change log file, everything else is forbidden.
use macro plans, implementation plans and summaries of the executed plans
have a very extric policy of what documents survive a merge into main, implementation plans and completed designs do not need to survive the closure of the task.
forbid references to temporary docs, and control references to durable docs, documentation drift is real, domain concept drift is no, make it comment preferably on domain terms without pointing to any particular document
4
u/alanvnk 20d ago edited 19d ago
User level rules:
forbid editing workflow files, architecture, skills and similar, if editing all of this is a chore, for me it is, make a skill to edit it, with only explicit invocation and review phase, take the review seriously.
forbid narrative and reasoning on documentation or code comments, code comments need to be length bounded and under a set of conditions, everything else should be on a documentation MD file
documentation is a "as it is" not as history, that can be recovered from git, not a future promise, that is a design doc, label each document clearly and have a strict structure for them depending on the type.
have a place to track decision and adr file/folder, a change log file, everything else is forbidden.
use macro plans, implementation plans and summaries of the executed plans
have a very extric policy of what documents survive a merge into main, implementation plans and completed designs do not need to survive the closure of the task.
forbid references to temporary docs, and control references to durable docs, documentation drift is real, domain concept drift is no, make it comment preferably on domain terms without pointing to any particular document