discover-docs-norms

Skill: Discover Docs Norms

Purpose

Discover and propose project-level documentation norms (paths, naming, front-matter, lifecycle), providing input basis for subsequently creating or updating norm files.

Core Objective

Primary objective: produce a reviewable norm proposal, without executing norm persistence.

Success criteria(all must be satisfied):

✅ Scanned the target docs scope and extracted existing conventions
✅ Output a norm proposal (including path mapping, naming rules, front-matter rules, confidence)
✅ Clearly identified conflicts and low-confidence items
✅ Provided next-step handoff recommendations (define-docs-norms）
✅ Did not write or overwrite docs/ARTIFACT_NORMS.md

Acceptance test: Can the team review and decide whether to persist based solely on the proposal, without modifying the repository structure?

Scope Boundaries

This skill is responsible for：

Scanning the docs structure and inferring documentation governance conventions
Forming proposals and marking confidence and conflicts
Outputting suggested canonical rules and migration hints

This skill is not responsible for：

Creating or updating docs/ARTIFACT_NORMS.md(use define-docs-norms）
Batch organizing file structure (use tidy-repo）
Compliance assessment and health scoring (use assess-docs）

Handoff point: after the proposal is confirmed, hand off to define-docs-norms to persist the norms.

Use Cases

Before the project's first governance effort, existing documentation conventions need to be identified first
When norms are disputed, a discussable candidate solution needs to be generated
In multi-team collaboration, unify candidate norms first before deciding whether to write them

Behavior

Phase 1: Scanning and Sampling

Scan docs/(if it does not exist, scan Markdown in the repository)
Read front-matter, paths, file names, titles
Extract artifact_type, naming patterns, date patterns, directory distribution

Phase 2: Rule Derivation

Generate candidate artifact_type -> path_pattern mappings
Derive naming rules (kebab/snake/camel, date prefix strategy)
Derive the minimal front-matter field set
Identify conflict distribution (multiple paths for the same type, multiple naming styles)

Phase 3: Confidence and Risk Assessment

Score each rule (0-100)
Mark low-confidence (< 70) rules
Provide conflict resolution recommendations (which path to keep, which files to migrate)

Phase 4: Output Proposal (read-only)

Generate docs/calibration/docs-norms-proposal.md
Output proposal structure: rule table, conflict table, migration recommendations, decision question list
Clarify next step: if it needs to take effect, execute define-docs-norms

Input & Output

Input

Project path (defaults to the current repository)
Optional docs root path
Optional confidence threshold

Output

docs/calibration/docs-norms-proposal.md(norm proposal)
Does not create/update docs/ARTIFACT_NORMS.md

Restrictions

Hard Boundaries

Without explicit user request, this skill must not write docs/ARTIFACT_NORMS.md
This skill must not perform repository organization or file moves
This skill must not disguise proposals as already-effective specifications

Skill Boundaries

Do not do these (other skills are responsible)：

Specification persistence and changes:define-docs-norms
Structural organization:tidy-repo
Compliance and readiness assessment:assess-docs

Self-Check

Scanned the target docs scope and extracted rule candidates
Output path/naming/front-matter proposals
Marked low-confidence and conflicting items
Provided handoff recommendations define-docs-norms
Not written docs/ARTIFACT_NORMS.md

Examples

Example 1: Only proposals found

Input: Existing project docs/ structure
Output:docs/calibration/docs-norms-proposal.md
Follow-up: After review approval, call define-docs-norms

Example 2: Multiple conflicting directory sets exist

Input: Both docs/design/ and docs/design-decisions/
Output: Conflict adjudication recommendations + migration checklist
Follow-up: By define-docs-norms solidify canonical rules

Appendix: Output Contract

This skill produces a Docs Norms Proposal (does not write the specification itself):

Element	Format	Required fields	Path pattern
Proposal body	Markdown	front-matter (artifact_type=proposal / lifecycle=snapshot); sections: scan results / proposed rules / differences from current state / risks	docs/calibration/docs-norms-proposal.md
Proposed rules	Table	rule_kind（path / naming / lifecycle）/ pattern / evidence_files / confidence	"Proposed rules" section
Differences from current state	List items	Instance paths in existing docs that violate this proposal; used to assess change cost	"Differences from current state" section