define-docs-norms

Skill: Define Docs Norms

Purpose

Solidify the reviewed norms proposal into docs/ARTIFACT_NORMS.md, and serve as the canonical rules for project documentation governance.

---

Core Objective

Primary Objective: Safely and audibly create or update project norms files.

Success Criteria(all must be satisfied):

1. ✅ The input proposal is clear and can be written to disk
2. ✅ The norms file structure conforms to the project schema and conventions
3. ✅ The change description is clear (added, modified, deleted rules)
4. ✅ Write targets are limited to docs/ARTIFACT_NORMS.md
5. ✅ After output, it can be directly consumed by runtime / linter / CI tools (per rules/doc-health-criteria.md）

Acceptance Test: Can the norms file be directly used as the basis for path/naming/front-matter validation and be stably parsed by other skills?

---

Scope Boundaries

This skill is responsible for：

• Creating or updating docs/ARTIFACT_NORMS.md
• Merging existing norms with new proposals (configurable strategy)
• Outputting a change summary and migration hints

This skill is not responsible for：

• Norms discovery and derivation (handled by humans or AgentFabric runtime)
• Repository organization and file migration (per rules/repo-structure-hygiene.md, executed by AgentFabric runtime or humans)
• Compliance auditing and readiness scoring (handled by runtime / linter / CI tools)

Handoff Point: After norms are written, structural remediation and compliance detection are executed by runtime / linter / CI tools per rules/repo-structure-hygiene.md and rules/doc-health-criteria.md .

---

Use Cases

• A new project establishes ARTIFACT_NORMS
• for the first time; an old project upgrades a proposal into formal rules
• Norms iteration and update (path, naming, field policies)

---

Behavior

Phase 1: Input Confirmation

1. Read the proposal (usually from docs/calibration/docs-norms-proposal.md）
2. Check whether an old version exists docs/ARTIFACT_NORMS.md
3. Confirm the write-to-disk strategy:create | merge | replace

Phase 2: Norms Assembly

1. Assemble path mapping, naming strategy, and front-matter standards
2. Write manual confirmation notes for low-confidence rules (if any)
3. Validate format consistency and parseability

Phase 3: Write to Disk and Summary

1. Write docs/ARTIFACT_NORMS.md
2. Output the change summary for this round (added/modified/deleted)
3. Output follow-up recommendations: runtime organizes per rules/repo-structure-hygiene.md + rules/doc-health-criteria.md compliance detection

---

Input & Output

Input

• Reviewed norms proposal
• Optional existing docs/ARTIFACT_NORMS.md
• Optional merge strategy (create|merge|replace）

Output

• docs/ARTIFACT_NORMS.md
• Change summary

---

Restrictions

Hard Boundaries

• Only writing to norms files is allowed; no repository structural changes are performed
• Stop and request confirmation when the input proposal is unclear
• Unconfirmed conflicting rules must not be marked as finalized

Skill Boundaries

Do not do these (other skills are responsible)：

• Discovery and derivation: humans or AgentFabric runtime
• Compliance scoring: runtime / linter / CI tools (per rules/doc-health-criteria.md）
• File organization: runtime per rules/repo-structure-hygiene.md execution

---

Self-Check

• Received rule input that can be persisted
• Correctly wrote to docs/ARTIFACT_NORMS.md
• Output rule change summary
• Did not perform non-standard file writes

---

Examples

Example 1: Create a new specification from a proposal

• Input:docs/calibration/docs-norms-proposal.md
• Behavior:create
• Output:docs/ARTIFACT_NORMS.md

Example 2: Incremental update to an old specification

• Input: old specification + new proposal
• Behavior:merge
• Output: updated specification file + change summary