optimize agent-docs

skills/agent-docs/references/rule-doc-template.md

@@ -2,7 +2,7 @@
 
 Use this structure for Markdown files inside `agent-docs/` when the document's main job is to govern behavior: rules, policy, constraints, decision criteria, or workflow guidance.
 
-## Recommended Shape
+## Minimum Required Shape
 
 ```md
 # <Document Title>
@@ -38,6 +38,21 @@ Use this structure for Markdown files inside `agent-docs/` when the document's m
 - <validation questions>
 ```
 
+## Required Sections
+
+- `# <Document Title>`
+- opening statement
+- `## Applies To`
+- `## Authority`
+- at least one topic-specific rule section
+- `## Checklist`
+
+## Conditionally Required Sections
+
+- `## Does Not Apply To` when scope boundaries are easy to misread or likely to overlap with sibling docs
+- `## Edge Cases` when branch conditions or exceptions would otherwise be inferred
+- `## Failure Modes` when maintainers need recovery guidance or common-mistake handling
+
 ## Notes
 
 - Make the scope explicit.
@@ -46,6 +61,6 @@ Use this structure for Markdown files inside `agent-docs/` when the document's m
 - Write for maintainers. State actions, constraints, and decision criteria directly.
 - If the document references repository files, write repository-relative paths in backticks, not Markdown links or machine-local absolute filesystem paths.
 - State the user or maintainer decision directly: what to do, what to avoid, and how to choose.
-- Add `Authority` when the rule depends on a repository fact, owning document, or other source of truth that later reviews must verify.
+- Treat `Authority` as required. If no authority can be named, the rule is probably too vague or not ready to be canonicalized.
 - Add `Edge Cases` and `Failure Modes` when the workflow is easy to misapply or the scope boundary is easy to misunderstand.
 - Prefer linking to inventories, examples, or narrower child docs instead of embedding long registries inline.