/ghm-sot-builder

name: ghm-sot-builder
description: >
  Creates new Source of Truth (SoT) files when existing templates don't fit your needs.
  Triggers on requests to create a new SoT file, add a new artifact type, or when user says
  "I need to track [X] but there's no SoT for it", "create SoT", "new source of truth".
  Outputs a properly structured SoT.*.md file with ID prefix, frontmatter, and update protocol.
context: fork
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep

SoT Builder

Create new Source of Truth files that fit your product's unique needs while maintaining template purity.

When to Use This Skill

This skill is for **rare occasions** (3-4 times per product lifecycle) when:

• You fork this repo and the existing SoT files don't cover your artifact types
• Your product needs to track a concept that doesn't fit existing ID prefixes
• You need to consolidate scattered documentation into a canonical SoT

**Do NOT use** when:

• An existing SoT file covers your need (just add entries there)
• You want to track temporary/session-specific data (use `temp/` instead)
• The artifact type is already covered by `ghm-id-register`

Workflow Overview

1. **Identify Need** → Confirm no existing SoT fits 2. **Design Schema** → Define ID prefix, categories, required fields 3. **Draft Template** → Create pure structure (no methodology teaching) 4. **Validate Purity** → Apply the litmus test 5. **Register & Integrate** → Update SoT.README.md and ID system

Core Output Template

See `assets/sot-template.md` for the copy-paste starter template.

| Element | Definition | Required | |---------|------------|----------| | **YAML Frontmatter** | version, purpose, id_prefix, authority | Yes | | **Purpose Block** | Single paragraph explaining what this tracks | Yes | | **Navigation Section** | Category links for quick access | Yes | | **Entry Template** | Repeatable structure for each ID | Yes | | **Cross-Reference Index** | Bidirectional links to other SoT files | Yes | | **Update Protocol** | When/how to add new entries | Yes |

Step 1: Identify the Need

Before creating a new SoT, verify:

Checklist

• [ ] Searched existing SoT files for similar artifact types
• [ ] Confirmed the concept is **durable** (survives multiple sessions)
• [ ] Confirmed the concept needs **unique IDs** for cross-referencing
• [ ] Confirmed this isn't better served by a subsection in an existing SoT

Questions to Answer

1. **What artifact type does this track?**

• Bad: "Notes" (too generic)
• Good: "Partner Integration Contracts" (specific, durable)

2. **Why can't existing SoT files handle this?**

• Valid: "We need different fields than API contracts for partner integrations"
• Invalid: "I just want a separate file" (preference, not need)

3. **What ID prefix will you use?**

• Must be unique across the system
• 2-4 uppercase letters
• Check `SoT/SoT.UNIQUE_ID_SYSTEM.md` for existing prefixes

Step 2: Design the Schema

Define the structure before writing:

ID Prefix Selection

Format: [PREFIX]-[XXX]
Examples: PIC-001, INT-042, MIG-003

**Rules**:

• 2-4 uppercase letters
• Descriptive but short
• Unique across all SoT files
• Check existing prefixes in `SoT/SoT.UNIQUE_ID_SYSTEM.md`

Category Ranges

Reserve ID ranges for logical groupings:

**Category A** (XXX-001 to XXX-099):
**Category B** (XXX-101 to XXX-199):
**Category C** (XXX-201 to XXX-299):

Required Fields per Entry

Define the minimum fields every entry needs:

| Field | Purpose | Example | |-------|---------|---------| | **ID** | Unique identifier | `PIC-001` | | **Title** | Human-readable name | "Stripe Payment Integration" | | **Status** | Current state | Active / Deprecated / Planned | | **Created** | Origin date | 2025-01-10 | | **Last Updated** | Last modification | 2025-01-15 | | **Related IDs** | Cross-references | BR-101, API-045 |

Optional Fields

Add domain-specific fields as needed, but keep them structural (not methodology):

• Good: "Partner Contact" (data field)
• Bad: "Best Practices for Partner Selection" (methodology teaching)

Step 3: Draft the Template

Use `assets/sot-template.md` as your starting point.

Structure Sections

1. **YAML Frontmatter** - Metadata for the file 2. **Title & Purpose Block** - What this SoT tracks 3. **Navigation by Category** - Quick links to entries 4. **Entry Template** - Repeatable structure (copy for each new entry) 5. **Deprecated Section** - Where old entries go 6. **Cross-Reference Index** - Bidirectional links 7. **Update Protocol** - When/how to maintain

Template Purity Rules

**KEEP in the template** (self-documentation):

• When to add new entries
• Required fields checklist
• Cross-reference integrity checks
• File-specific maintenance procedures

**MOVE to skill references** (methodology teaching):

• "Best practices" for this domain
• "What makes a good entry"
• Example workflows beyond format
• Evaluation criteria

Litmus Test

For each section, ask:

> "Is this teaching me how to maintain the FILE STRUCTURE, or teaching me DOMAIN KNOWLEDGE about what makes good content?"

• File structure maintenance → Keep in template
• Domain knowledge → Move to skill references

Step 4: Validate Purity

Before finalizing, run this checklist:

Purity Checklist

• [ ] No "how to analyze" or "how to evaluate" content
• [ ] No "best practices" or "key learnings" sections
• [ ] No cross-file workflows (multi-file coordination)
• [ ] No "what makes a good entry" evaluation criteria
• [ ] Examples show FORMAT only, not instructional CONTENT
• [ ] Self-documentation is under 20% of total file size

Self-Documentation Checklist

• [ ] Has "Update Protocol" section
• [ ] Documents when to add new IDs
• [ ] Includes cross-reference integrity checks
• [ ] Specifies required fields for new entries
• [ ] Self-documentation is file-specific (not generic)

Context Efficiency Checklist

• [ ] Template can be read