home / skills / mattgierhart / prd-driven-context-engineering / ghm-id-register

ghm-id-register skill

safe

This skill validates and registers new SoT IDs with cross-reference integrity, ensuring format, uniqueness, and correct cross-links across BR, UJ, API, and CFD

npx playbooks add skill mattgierhart/prd-driven-context-engineering --skill ghm-id-register

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

3.5 KB

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

# 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

## Step 4: Register Entry

Add formatted entry to SoT file:

```markdown
### [ID]: [Title]

**Status**: Draft
**Created**: YYYY-MM-DD
**Cross-References**: [List of related IDs]

[Description]

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

## Quality Gates

### Pass Checklist
- [ ] ID format is valid
- [ ] ID is unique within its domain
- [ ] All cross-references resolve
- [ ] Entry follows SoT template

### Testability Check
- [ ] ID can be searched and found
- [ ] Cross-references are bidirectional (if required)

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

## 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 valid
- EPIC Section 3A updated with new ID
- Ready for implementation

Overview

This skill validates and registers new Source-of-Truth (SoT) IDs with cross-reference integrity checks. It enforces ID format, ensures uniqueness, verifies that all referenced IDs exist, and outputs a formatted SoT entry ready to append to the correct domain file. It triggers automatically for BR-XXX, UJ-XXX, API-XXX, and CFD-XXX entries.

How this skill works

When a new ID is created, the skill checks the prefix and zero-padded 3-digit pattern, then scans the target SoT file to confirm the ID is unique. It parses any referenced IDs, looks them up in their respective SoT files, and flags missing or mismatched references. If all gates pass, it produces a standardized markdown entry with status, creation date, cross-references, description placeholder, and acceptance criteria for registration.

When to use it

When creating a new business rule (BR-XXX) entry
When adding a new user journey (UJ-XXX) item
When registering a new API contract (API-XXX)
When logging customer feedback items (CFD-XXX)
When you need to ensure cross-reference integrity across SoT files

Best practices

Always use the correct prefix for the domain (BR, UJ, API, CFD)
Keep IDs zero-padded to three digits (e.g., BR-005) to avoid formatting errors
Run the uniqueness check before editing content to prevent duplicate IDs
Include all related IDs in Cross-References and resolve them prior to registration
Use the generated template fields (Status, Created, Cross-References, Acceptance Criteria) to maintain consistency

Example use cases

Auto-assign the next available BR-XXX when creating new business rules
Validate that a new API contract references only existing UJ-XXX and BR-XXX entries
Prevent registration of CFD-XXX that cites nonexistent product or journey IDs
Produce a ready-to-paste SoT entry for PRD or implementation handoff
Gate deployment readiness by ensuring cross-references are bidirectional if required

FAQ

What ID formats are accepted?

Only BR, UJ, API, and CFD prefixes followed by a zero-padded three-digit number (e.g., API-012).

What happens if a referenced ID is missing?

The skill flags the missing references and prevents registration until all referenced IDs are created or corrected.

Can the skill auto-assign IDs?

Yes. If enabled, it will pick the highest existing ID with the same prefix and increment by one, formatted with three digits.