mattgierhart/ghm-sot-builder

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 without loading other files
• [ ] Methodology examples are in skill references, not template
• [ ] General governance references SoT.README.md

Step 5: Register and Integrate

After creating the SoT file:

Update SoT.README.md

Add entry to the structure table:

| `SoT.{YOUR_FILE}.md` | {PREFIX}-### | {Purpose description} |

Update SoT.UNIQUE_ID_SYSTEM.md

Add new prefix to Section 1.2 Standard Prefixes:

| **{PREFIX}** | {Meaning} | `SoT.{YOUR_FILE}.md` |

Create Index Tables

Add empty index table in Part 2 of SoT.UNIQUE_ID_SYSTEM.md:

#### {Your Type} ({PREFIX}-XXX)

| ID | Title | Status | Used By |
|----|-------|--------|---------|
| {PREFIX}-001 | {Title} | Active | {IDs} |

Quality Gates

Pass Checklist

• [ ] ID prefix is unique across all SoT files
• [ ] Template follows purity standard
• [ ] Update protocol included
• [ ] Cross-reference index structure defined
• [ ] SoT.README.md updated
• [ ] SoT.UNIQUE_ID_SYSTEM.md updated

Testability Check

• [ ] Can create a new entry using only the template instructions
• [ ] Cross-references can be validated programmatically
• [ ] Entries can be found by ID search

Anti-Patterns

| Pattern | Example | Fix | |---------|---------|-----| | Methodology in template | "Best practices for partner selection" | Move to skill references | | Duplicate prefix | Using BR- for a new file | Choose unique prefix | | Too generic | "Notes.md" | Be specific: "Partner_Integrations.md" | | No update protocol | Template with no maintenance section | Add "Update Protocol" section | | Orphan SoT | Not registered in SoT.README.md | Always register new files |

Bundled Resources

• references/sot-patterns.md — Common patterns across existing SoT files
• references/examples.md — Before/after examples of SoT creation
• assets/sot-template.md — Copy-paste starter template

Handoff

After creating a new SoT:

1. SoT file exists at SoT/SoT.{NAME}.md
2. SoT.README.md lists the new file
3. SoT.UNIQUE_ID_SYSTEM.md has the new prefix
4. Ready to use ghm-id-register for adding entries