help-docs-contract

name	help-docs-contract
description	Use when creating or updating in-app help content — tooltips, empty states, contextual panels, help articles — or auditing help coverage, identifiers, and accuracy.

Help Docs Contract

This skill defines the non-negotiable contract for creating in-app help documentation that is contextual, accessible, UI-aware, and verifiably accurate.

It is authoritative and intended to be reused across projects.

---

Scope

This skill applies whenever an agent:

• Creates or updates help documentation
• Designs an in-app help system
• Adds tooltips, empty states, contextual panels, or help articles
• Creates documentation identifiers, anchors, or cross-linking structures
• Performs documentation audits or coverage analysis

---

Core Contract

1. Behaviour–Truth Rule (Ship Blocker)

Help content MUST reflect current, observable system behaviour, not intent, roadmap, or assumptions.

• If behaviour cannot be verified, the content MUST be marked as unverified and excluded from shippable deliverables.
• “Soon” or “will” language is prohibited in shipped help.

---

2. Single-Intent Rule (Ship Blocker)

Every help unit MUST have exactly one primary intent:

• tutorial — guided learning
• how_to — goal-oriented steps
• explanation — conceptual understanding
• reference — lookup

Help units MUST NOT mix intents.

---

3. Identifier Stability Rule (Ship Blocker)

Every help unit MUST have stable identifiers:

• doc_id — unique, human-readable, stable once published
• feature_id — stable feature identifier used for coverage tracking
• ui_anchor_id — stable UI anchor identifier tied to a specific screen or region

Identifiers MUST be:

• Human-readable
• Stable once published
• Independent of implementation details
  (Do not encode file paths, component names, or internal IDs.)

---

4. UI Anchoring Rule

Each help unit MUST define:

• Where it opens from in the UI (launch points)
• Which screen or region it references
• Whether it can optionally highlight or focus the referenced region

Help MUST open without leaving the app and MUST offer a safe return path after any UI jump.

---

5. Accessibility Requirements (Ship Blocker)

Help content and help UI MUST:

• Use proper heading hierarchy
• Use descriptive link text
• Include meaningful alt text for images or diagrams
• Never rely on colour alone for meaning
• Be fully keyboard usable

Accessibility failures are ship blockers.

---

6. Terminology Single Source of Truth

Help MUST match UI labels exactly.

• Do not invent synonyms for UI labels
• Define technical terms once and reuse consistently
• Maintain a glossary or terminology reference if needed

---

7. Verification Metadata (Required)

Each help unit MUST record:

• introduced_at — date or version
• last_verified_at — date or version
• verification_scope — what was verified
  (UI labels, permissions, states, behaviour)

Help that depends on conditional or experimental behaviour MUST be explicitly flagged.

---

When NOT to Apply

• Developer-facing docs (READMEs, API references) — different audience and conventions
• Marketing or blog content — persuasion, not instruction
• Ad-hoc answers in chat — the contract governs shipped help units, not conversation

---

Enforcement

If any ship-blocker rule is violated, the agent MUST:

• Stop
• Report the violation
• Propose a compliant fix, or mark the content as unshippable

---

Intent

This skill exists to prevent:

• Documentation that drifts from the product
• Unverifiable “future docs”
• Inaccessible help systems
• Broken cross-links and unstable identifiers
• Mixed-intent help that confuses users