name	ground-truth-template
description	Generic ground truth documentation template for creating verifiable reference skills. Auto-invoke when user requests ground truth skill creation, validation criteria framework, or canonical documentation templates. Do NOT load during actual ground truth usage (use project-specific skills instead).
allowed-tools	["Grep"]
version	1.0.0
category	Templates
tags	["template","ground-truth","validation","reference-data"]
last-updated	"2025-10-20T00:00:00.000Z"

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

---
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:

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_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):

[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:

[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:

- 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):

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:

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:

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:

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:

⚠️ 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

name	ground-truth-template
description	Generic ground truth documentation template for creating verifiable reference skills. Auto-invoke when user requests ground truth skill creation, validation criteria framework, or canonical documentation templates. Do NOT load during actual ground truth usage (use project-specific skills instead).
allowed-tools	["Grep"]
version	1.0.0
category	Templates
tags	["template","ground-truth","validation","reference-data"]
last-updated	"2025-10-20T00:00:00.000Z"

Ground Truth Documentation Template

Purpose

SKILL.md Frontmatter Template

---
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:

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_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):

[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:

[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:

- 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):

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:

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:

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:

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:

⚠️ 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

export default ground-truth-template

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

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]`

Term: `[TERM_NAME]`

Fact Category: `[CATEGORY_NAME]`

Process: `[PROCESS_NAME]`

Validation Domain: `[DOMAIN_NAME]`

Error Category: `[CATEGORY]`

Enumeration: `[ENUM_NAME]`