bluecraft/skills/agent-docs/references/refactor-checklist.md

Refactor Checklist

Use this checklist after changing the root AGENTS.md or any file in agent-docs/.

• Does each covered document own one clear topic?
• Does each filename clearly express the document's purpose?
• Does each opening explain purpose, trigger, and that the document must be followed in scope?
• Is the root AGENTS.md still the starting point for required agent-docs?
• Does every active agent-docs/ file have an explicit path from the root?
• Does each child doc use the right shape for its job: rule doc versus inventory doc?
• Did you remove stale references, filenames, and replaced paths?
• Did you delete or update any agent-docs file that is no longer referenced from the root AGENTS.md?
• Did you avoid duplicating the same rule across multiple active docs?
• Did you avoid mixing long entry inventories into rule docs when a separate inventory would be clearer?
• Did you avoid adding an intermediate router or index doc that only repeats links?
• If you split a doc, did the split reduce ambiguity, repetition, or maintenance cost?
• If a document grew broader, did you check whether it now owns more than one real decision surface and should be split?
• If a workflow is fragile or easy to misapply, did you add explicit edge cases or failure modes instead of hiding them in prose?
• Is the default path basis still the root of the current Git working tree unless explicitly overridden?
• Are repository-wide constraints still in the root file?
• Are topic-specific constraints still in child docs?
• Are project-specific rules still kept in project-specific documents rather than the general rules layer?
• Did you avoid mixing general agent-doc governance with project-specific business rules or end-user documentation?
• Do repository file references still use plain repository-relative paths in backticks rather than Markdown links or machine-local absolute paths?
• Did you keep reference depth minimal?
• Does the root still act like a route map instead of a topic dump?
• If the repository has a validation command, did you run it?