/ghm-id-register

name: ghm-id-register
description: >
  Validates and registers new SoT IDs with cross-reference integrity.
  Triggers when creating BR-XXX, UJ-XXX, API-XXX, or CFD-XXX entries.
  Outputs formatted SoT entry with validated cross-references.
context: fork
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep

ID Register

Validate and register new Source of Truth IDs with cross-reference integrity checks.

Workflow Overview

1. **Validate Format** → Check ID follows `[PREFIX]-[3-digit]` pattern 2. **Check Uniqueness** → Ensure ID doesn't already exist 3. **Verify Cross-Refs** → All referenced IDs must exist 4. **Register Entry** → Add to appropriate SoT file

Core Output Template

| Element | Definition | Evidence | |---------|------------|----------| | **ID** | Unique identifier | `BR-101`, `UJ-045`, `API-012` | | **Title** | Short descriptive name | Clear, specific | | **Cross-References** | Links to related IDs | All referenced IDs exist | | **Status** | Current state | Draft / Active / Deprecated |

ID Format Reference

| Prefix | Domain | File | |--------|--------|------| | `BR-` | Business Rules | `SoT/SoT.BUSINESS_RULES.md` | | `UJ-` | User Journeys | `SoT/SoT.USER_JOURNEYS.md` | | `API-` | API Contracts | `SoT/SoT.API_CONTRACTS.md` | | `CFD-` | Customer Feedback | `SoT/SoT.customer_feedback.md` |

Step 1: Validate Format

Check ID follows the pattern:

[PREFIX]-[XXX]

Where:

• PREFIX = BR, UJ, API, or CFD
• XXX = 3-digit number (zero-padded)

Checklist

• [ ] Prefix is valid (BR, UJ, API, CFD)
• [ ] Number is 3 digits
• [ ] Format matches `[A-Z]+-[0-9]{3}`

Step 2: Check Uniqueness

1. Read target SoT file 2. Extract all existing IDs of same prefix 3. Verify new ID doesn't exist 4. If auto-assigning: use highest existing + 1

Checklist

• [ ] Target SoT file read
• [ ] Existing IDs enumerated
• [ ] New ID is unique

Step 3: Verify Cross-References

For each ID referenced in the new entry: 1. Identify the prefix 2. Check that ID exists in its SoT file 3. Flag any missing references

Checklist

• [ ] All `BR-XXX` references exist in BUSINESS_RULES
• [ ] All `UJ-XXX` references exist in USER_JOURNEYS
• [ ] All `API-XXX` references exist in API_CONTRACTS
• [ ] All `CFD-XXX` references exist in CUSTOMER_FEEDBACK
• [ ] Each cross-reference includes a relationship type (see `references/cross-reference-patterns.md`)
• [ ] Relationship types match the directional hierarchy (vertical types for cross-layer, lateral types for same-layer)

Step 3.5: Evaluate Confidence (NEW)

Before registering, assign a confidence score (1-5) based on evidence strength:

| Score | Evidence Level | Examples | |-------|----------------|----------| | 1/5 | Assumption / PM decision | "We think users want X" | | 2/5 | Secondary research | Competitive analysis, market report | | 3/5 | Direct feedback | User interviews (3-5 conversations) | | 4/5 | Validated behavior | Beta testing, small-scale usage | | 5/5 | Production evidence | Real usage data at scale |

**Question to ask**: What's the highest evidence supporting this entry right now? What would move it to the next confidence level?

**Example confidence annotations**:

• `confidence: 2/5, source: competitive-analysis`
• `confidence: 3/5, source: 5-user-interviews-jan-2026`
• `confidence: 4/5, source: beta-cohort-validation`

See `.claude/skills/PRINCIPLES.md` for detailed confidence model by SoT type.

Checklist

• [ ] Confidence score assigned (1-5)
• [ ] Highest evidence source identified
• [ ] Forward path identified ("would move to X/5 if...")

Step 4: Register Entry

Add formatted entry to SoT file:

### [ID]: [Title]

**Status**: Draft
**Created**: YYYY-MM-DD
**Confidence**: [1-5]/5 (source: [evidence source])
**Next Confidence Target**: [What would move this to next level]
**Cross-References**: [List of related IDs]

[Description]

**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2

**Example entry with confidence**:

### CFD-042: Users want dark mode

**Status**: Active
**Created**: 2026-02-01
**Confidence**: 3/5 (source: 5-user-interviews-jan-2026)
**Next Confidence Target**: 4/5 (would require beta cohort validation)
**Cross-References**: FEA-008 (dark mode feature)

During interviews, 4 of 5 users mentioned desire for dark mode. Competitors (Notion, Linear, Figma) all have it.

**Acceptance Criteria**:
- [ ] Feature FEA-008 delivered to beta cohort
- [ ] Track usage: % of beta users enabling dark mode

Quality Gates

Pass Checklist

• [ ] ID format is valid
• [ ] ID is unique within its domain
• [ ] All cross-references resolve
• [ ] Entry follows SoT template
• [ ] Confidence score assigned (1-5) with source documented
• [ ] Next confidence target identified

Testability Check

• [ ] ID can be searched and found
• [ ] Cross-references are bidirectional (if required)
• [ ] Confidence score is honest (reflects actual evidence, not wishful thinking)

Anti-Patterns

| Pattern | Example | Fix | |---------|---------|-----| | Duplicate ID | Creating BR-101 when it exists | → Check uniqueness first | | Orphan reference | References UJ-999 that doesn't exist | → Verify all cross-refs | | Wrong prefix | Using BR- for an API contract | → Match prefix to domain | | Missing zero-pad | BR-5 instead of BR-005 | → Always use 3 digits | | Inflated confidence | Assigning 4/5 to a PM assumption | → Be honest about evidence level | | No confidence source | "confidence: 3/5" with no source | → Always record source (CFD-001, user-interview-jan, etc.) | | Missing confidence target | Confidence assigned but no forward path | → Ask "what would move this to 4/5?" |

Boundaries

**DO**:

• Format validation
• Uniqueness checks
• Cross-reference verification
• Entry formatting

**DON'T**:

• Content decisions about ID meaning
• Approve/reject based on business logic
• Modify existing IDs

Handoff

After ID registration:

• New ID is in SoT file
• Cross-references are vali