Skill: Discover Document Norms

Purpose

Help users define their project-specific artifact norms (paths, naming, lifecycle) for document governance. Projects may have their own documentation structure; this skill discovers and formalizes it so other skills (capture-work-items, brainstorm-design, assess-doc-readiness) can follow project norms.

Core Objective

Primary Goal: Produce docs/ARTIFACT_NORMS.md (and optionally .ai-cortex/artifact-norms.yaml ) that declares the project's artifact paths, naming, and lifecycle for backlog, design, ADR, and calibration artifacts.

Success Criteria (ALL must be met):

• ✅ Project structure scanned: Existing docs/ structure and conventions inspected

• ✅ User preferences confirmed: Paths for backlog, design, adr, doc-readiness confirmed via dialogue (or accepted from starting template)

• ✅ ARTIFACT_NORMS.md written: Human-readable norms file at docs/ARTIFACT_NORMS.md

• ✅ Optional YAML created: If user requests, .ai-cortex/artifact-norms.yaml written with machine-readable schema

• ✅ User confirmed: User explicitly approved the norms before final write

Acceptance Test: Can another skill (e.g. capture-work-items) read the output and correctly resolve paths for this project?

Scope Boundaries

This skill handles:

• Scanning project docs/ structure

• Dialogue to confirm artifact paths and naming

• Generating docs/ARTIFACT_NORMS.md and optional .ai-cortex/artifact-norms.yaml per spec/artifact-norms-schema.md

• Starting from AI Cortex default, project-documentation-template, or blank

This skill does NOT handle:

• Bootstrapping full project docs (use bootstrap-docs )

• Assessing doc readiness (use assess-doc-readiness )

• Validating existing docs against norms (use validate-doc-artifacts )

Handoff point: When norms are written and confirmed, hand off to other document-producing skills or validate-doc-artifacts for compliance checks.

Use Cases

• New project: No artifact norms yet; user wants to establish them before using capture-work-items or brainstorm-design.

• Existing project: Project has custom docs/ structure; formalize it so skills align.

• Migration: Adopting AI Cortex defaults or project-documentation-template; create norms file for consistency.

Behavior

Interaction Policy

• Defaults: Project path = workspace root; start from AI Cortex defaults if no norms

• Choice options: Starting point [ai-cortex][template][blank] ; path mapping per artifact type

• Confirm: Before writing ARTIFACT_NORMS.md; all path mappings

Phase 1: Scan

• Inspect project root and docs/ (if exists)

• Identify existing paths: backlog, design, adr, calibration, etc.

• Note any conventions (naming, front-matter) from sample files

Phase 2: Choose Starting Point

Ask user or infer from context:

• AI Cortex default: Use spec/artifact-contract.md as baseline

• project-documentation-template: Map template structure to artifact types

• Blank: Start with minimal table, user fills in paths

Phase 3: Confirm Paths

For each artifact type (backlog-item, design, adr, doc-readiness):

• Propose path_pattern and naming from starting point or existing structure

• Ask user to confirm or customize

• Document Path Detection rules for backlog-item if applicable

Phase 4: Write and Confirm

• Generate docs/ARTIFACT_NORMS.md per spec/artifact-norms-schema.md

• Optionally generate .ai-cortex/artifact-norms.yaml

• Present summary; request user confirmation before writing

• Write files after confirmation

Input & Output

Input

• Project path (default: current workspace root)

• Optional: starting point (ai-cortex | template | blank)

Output

• docs/ARTIFACT_NORMS.md : Human-readable artifact norms table

• .ai-cortex/artifact-norms.yaml (optional): Machine-readable schema

Restrictions

Hard Boundaries

• No overwrite without confirmation: Do not write or overwrite norms files without explicit user approval.

• Schema compliance: Output MUST follow spec/artifact-norms-schema.md.

Skill Boundaries (Avoid Overlap)

Do NOT do these (other skills handle them):

• Full docs bootstrap → bootstrap-docs

• Readiness assessment → assess-doc-readiness

• Compliance validation → validate-doc-artifacts

Self-Check

Core Success Criteria (ALL must be met)

• Project structure scanned: Existing docs/ inspected

• User preferences confirmed: Paths confirmed via dialogue

• ARTIFACT_NORMS.md written: File exists at docs/ARTIFACT_NORMS.md

• User confirmed: User approved before write

Acceptance Test

Can another skill read the output and correctly resolve paths for this project?

If NO: Norms incomplete or inconsistent. Return to Phase 3. If YES: Handoff complete.

Examples

Example 1: New Project, AI Cortex Default

Context: Empty project, no docs/.

Steps: Start from AI Cortex default. Propose paths: docs/backlog/ , docs/design-decisions/ , docs/process-management/decisions/ , docs/calibration/ . User confirms. Write docs/ARTIFACT_NORMS.md and create docs/ subdirs as needed.

Example 2: Existing Custom Structure

Context: Project has docs/work-items/ , docs/decisions/ , no formal norms.

Steps: Scan structure. Propose mapping: backlog-item → docs/work-items/ , adr → docs/decisions/ . User confirms. Write norms file with custom paths.

Appendix: Output contract

This skill produces document-artifact outputs for project norms. Output MUST conform to:

Element Requirement

Primary output docs/ARTIFACT_NORMS.md — human-readable artifact norms table (artifact_type, path_pattern, naming, lifecycle)

Optional output .ai-cortex/artifact-norms.yaml — machine-readable schema per spec/artifact-norms-schema.md

Path mapping Each artifact_type mapped to a path_pattern; user must confirm before write