Ground Truth Documentation Template

Purpose

This template guides the creation of ground truth skills - verifiable, canonical reference documentation that provides definitive facts, definitions, and validation criteria. Replace all [PLACEHOLDER] values with actual verified information.

SKILL.md Frontmatter Template

yaml

---
name: [project]-[domain]-ground-truth
description: Ground truth documentation for [PROJECT_NAME] [DOMAIN] providing canonical definitions, verified facts, and validation criteria. Auto-invoke when user discusses [TOPIC_1], [TOPIC_2], or validates [VALIDATION_SCENARIO]. Do NOT load for general [DOMAIN] discussions without [PROJECT_NAME] context.
allowed-tools: []
version: 1.0.0
category: Ground Truth
tags: [[project], [domain], reference, validation]
source: [CANONICAL_SOURCE_URL_OR_LOCATION]
verified-date: [YYYY-MM-DD]
next-review: [YYYY-MM-DD]
---

Description Engineering Guidance:

✅ DO include:

•Specific topics covered (definitions, metrics, processes)
•Validation scenarios where ground truth applies
•Canonical source attribution
•Version or release reference if applicable

❌ DON'T use:

•Generic descriptions ("Provides information about...")
•No source attribution
•No scope boundaries (will load for irrelevant discussions)

Example Good Description:

code

Ground truth documentation for Phoenix payment processing providing canonical transaction states, error codes, and retry policies. Auto-invoke when user discusses payment flows, error handling, or validates transaction logic. Do NOT load for general payment discussions outside Phoenix.

Ground Truth Content Structure

1. Canonical Definitions

Purpose: Single source of truth for terms, concepts, and classifications

Term: `[TERM_NAME]`

Definition: [PRECISE_CANONICAL_DEFINITION]

Source: [AUTHORITATIVE_SOURCE] (verified [DATE])

Related Terms:

•[RELATED_TERM_1]: [BRIEF_DEFINITION]
•[RELATED_TERM_2]: [BRIEF_DEFINITION]

Anti-Patterns (What this is NOT):

•❌ [COMMON_MISCONCEPTION_1]
•❌ [COMMON_MISCONCEPTION_2]

Example Usage:

code

[CODE_EXAMPLE_OR_REAL_WORLD_USAGE]

2. Verified Facts & Metrics

Purpose: Quantifiable, verifiable information with sources

Fact Category: `[CATEGORY_NAME]`

Metric/Fact	Value	Source	Verified Date
`[METRIC_1]`	`[VALUE]` `[UNIT]`	`[SOURCE_LINK]`	`[YYYY-MM-DD]`
`[METRIC_2]`	`[VALUE]` `[UNIT]`	`[SOURCE_LINK]`	`[YYYY-MM-DD]`
`[METRIC_3]`	`[VALUE]` `[UNIT]`	`[SOURCE_LINK]`	`[YYYY-MM-DD]`

Calculation Method (if applicable):

code

[FORMULA_OR_CALCULATION_METHODOLOGY]

Freshness Policy:

•Update Frequency: [DAILY/WEEKLY/MONTHLY/QUARTERLY]
•Staleness Threshold: Data older than [TIME_PERIOD] requires reverification
•Last Verified: [YYYY-MM-DD]

3. Canonical Processes & States

Purpose: Definitive workflows, state machines, and process flows

Process: `[PROCESS_NAME]`

States:

code

[STATE_1] → [STATE_2] → [STATE_3] → [FINAL_STATE]

State Transitions:

From State	Event/Trigger	To State	Constraints
`[STATE_1]`	`[EVENT_1]`	`[STATE_2]`	`[CONDITION]`
`[STATE_2]`	`[EVENT_2]`	`[STATE_3]`	`[CONDITION]`
`[STATE_3]`	`[EVENT_3]`	`[FINAL_STATE]`	`[CONDITION]`

Error States:

•[ERROR_STATE_1]: Triggered by [ERROR_CONDITION] → Recovery: [RECOVERY_PROCESS]
•[ERROR_STATE_2]: Triggered by [ERROR_CONDITION] → Recovery: [RECOVERY_PROCESS]

Source: [TECHNICAL_SPEC_LINK_OR_DOC] (version [VERSION], dated [DATE])

4. Validation Criteria

Purpose: Definitive rules for validating implementations, data, or behaviors

Validation Domain: `[DOMAIN_NAME]`

Required Properties:

yaml

- Property: [PROPERTY_1]
  Type: [DATA_TYPE]
  Constraints: [VALIDATION_RULES]
  Example Valid: [VALID_EXAMPLE]
  Example Invalid: [INVALID_EXAMPLE]

- Property: [PROPERTY_2]
  Type: [DATA_TYPE]
  Constraints: [VALIDATION_RULES]
  Example Valid: [VALID_EXAMPLE]
  Example Invalid: [INVALID_EXAMPLE]

Business Rules:

•
[RULE_1]: [DETAILED_DESCRIPTION]
- •Valid Example: [EXAMPLE]
- •Invalid Example: [COUNTER_EXAMPLE]
•
[RULE_2]: [DETAILED_DESCRIPTION]
- •Valid Example: [EXAMPLE]
- •Invalid Example: [COUNTER_EXAMPLE]

Validation Test Cases (Reference):

code

Test ID: [TEST_ID]
Description: [WHAT_IS_BEING_TESTED]
Input: [TEST_INPUT]
Expected Output: [EXPECTED_RESULT]
Source: [TEST_SPEC_LOCATION]

5. Error Codes & Messages

Purpose: Canonical error taxonomy with meanings and resolutions

Error Category: `[CATEGORY]`

Error Code	Error Name	Meaning	Resolution	Severity
`[CODE_1]`	`[NAME]`	`[DESCRIPTION]`	`[FIX_STEPS]`	`[CRITICAL/HIGH/MEDIUM/LOW]`
`[CODE_2]`	`[NAME]`	`[DESCRIPTION]`	`[FIX_STEPS]`	`[CRITICAL/HIGH/MEDIUM/LOW]`

Error Code Format:

code

Pattern: [REGEX_PATTERN_OR_FORMAT]
Example: [EXAMPLE_ERROR_CODE]

6. Reference Data & Enumerations

Purpose: Canonical lists, enumerations, and classification schemes

Enumeration: `[ENUM_NAME]`

Value	Display Name	Description	Deprecated?
`[VALUE_1]`	`[DISPLAY_1]`	`[DESCRIPTION]`	No
`[VALUE_2]`	`[DISPLAY_2]`	`[DESCRIPTION]`	No
`[VALUE_3]`	`[DISPLAY_3]`	`[DESCRIPTION]`	⚠️ Yes (since `[DATE]`)

Source: [API_SPEC_OR_SCHEMA_LOCATION]

Validation Checklist

Before finalizing ground truth skill, verify:

Content Quality:

• All [PLACEHOLDERS] replaced with actual verified values
• Zero PII (no names, emails, phone numbers)
• Zero business-confidential metrics (use relative values or omit)
• All facts sourced and dated
• All definitions from canonical sources

Source Attribution:

• Every fact has a source reference
• Source links are accessible (internal docs, public APIs, etc.)
• Verification dates included
• Next review date set (freshness policy)

Validation Quality:

• Examples include both valid and invalid cases
• Business rules are unambiguous
• Error codes are complete and current
• State transitions are comprehensive

Metadata & Tracking:

• source field in frontmatter points to canonical documentation
• verified-date is current
• next-review date set based on freshness policy
• allowed-tools: [] set (ground truth is read-only reference)
• Category and tags aid discovery

Security & Scope:

• File location matches scope (project ground truth in .claude/skills/projects/[name]/ground-truth/)
• No sensitive implementation details exposed
• Reviewed by subject matter expert

Usage Examples

Creating New Ground Truth Skill:

code

User: "Create a ground truth skill for Phoenix payment error codes"

Claude: [Loads this template skill, uses structure to create Phoenix-specific ground truth]

Validating Implementation:

code

User: "Is this transaction state valid according to ground truth?"

Claude: [Loads project ground truth skill, checks against canonical state definitions]

Do NOT Use This Template For:

•Actual ground truth reference (use project-specific skills instead)
•Stakeholder information (use stakeholder template)
•Product roadmaps (use product template - roadmaps change frequently)
•Opinion or subjective content (ground truth is objective, verifiable facts only)

Freshness & Maintenance

Update Triggers:

•New product release with API changes
•Schema version updates
•Error code additions or changes
•Process flow modifications
•Quarterly review (minimum)

Staleness Warning: If next-review date has passed, skill should display:

code

⚠️ STALE GROUND TRUTH: Last verified [DATE], review overdue by [DAYS] days.
Please reverify before relying on this information.

Version Control:

•Track changes in git with descriptive commit messages
•Reference source documentation version in commits
•Update version field using semantic versioning (1.0.0 → 1.1.0 for additions)

Template Source: Phase 2 requirements + validation framework Template Version: 1.0.0 Last Updated: 2025-10-20 Validation: Ready for Phase 2 implementation

Ground Truth Documentation Template

Purpose

SKILL.md Frontmatter Template

Ground Truth Content Structure

1. Canonical Definitions

Term: [TERM_NAME]

2. Verified Facts & Metrics

Fact Category: [CATEGORY_NAME]

3. Canonical Processes & States

Process: [PROCESS_NAME]

4. Validation Criteria

Validation Domain: [DOMAIN_NAME]

5. Error Codes & Messages

Error Category: [CATEGORY]

6. Reference Data & Enumerations

Enumeration: [ENUM_NAME]

Validation Checklist

Usage Examples

Freshness & Maintenance

Term: `[TERM_NAME]`

Fact Category: `[CATEGORY_NAME]`

Process: `[PROCESS_NAME]`

Validation Domain: `[DOMAIN_NAME]`

Error Category: `[CATEGORY]`

Enumeration: `[ENUM_NAME]`