nextura-ssot-maintainer

Original source / Raw SKILL.md

---
name: nextura-ssot-maintainer
scope: nextura
description: >
  Maintain YAML-based SSOT for architecture artifacts.
  Use when creating requirements, components, decisions, or flows.
  Never edit generated files - edit YAML, then regenerate.
version: 2.0.0
triggers:
  - create requirement
  - create component
  - add decision
  - add ADR
  - create flow
  - add vendor
  - trace requirement

gates:
  pre:
    - "test -d data"
  post:
    - "make validate"
    - "make check-refs"
---

# SSOT Maintainer

Maintain Single Source of Truth for architecture artifacts. All data in YAML. All docs/diagrams generated.

**Golden Rule:** Edit YAML -> Run `make generate` -> Docs update

---

## Quick Start

1. Check if entity exists in data/
2. Create/edit YAML file
3. Run `make validate`
4. Run `make generate`
5. Run `make check-refs` (bidirectional links)

---

## Data Structure

```
data/
├── repos/{repo}/              # Per-repository
│   ├── _repo.yaml
│   ├── components/
│   ├── flows/
│   └── decisions/
│
├── domains/{domain}/          # Business domains
│   ├── _domain.yaml
│   ├── requirements/
│   └── decisions/
│
├── enterprise/                # Enterprise-wide
│   ├── vendors/
│   ├── standards/
│   └── decisions/

generated/                     # NEVER EDIT
├── docs/
└── diagrams/
```

**For detailed schemas:** See [reference/schemas.md](reference/schemas.md)

---

## Entity Creation Workflow

1. **Requirement:** `data/domains/{domain}/requirements/REQ-XXX.yaml`
2. **Component:** `data/repos/{repo}/components/C-XXX.yaml`
3. **Decision:** `data/enterprise/decisions/ADR-XXX.yaml`
4. **Flow:** `data/repos/{repo}/flows/FLOW-XXX.yaml`

**For entity templates:** See [reference/templates.md](reference/templates.md)

---

## Bidirectional References

When A references B, B must reference A:

| A has | B must have |
|-------|-------------|
| `traces_to: [B]` | `derived_from: [A]` |
| `satisfies: [B]` | `traces_to: [A]` |
| `affects: [B]` | `informed_by: [A]` |

Check with: `make check-bidirectional`

---

## STOP GATES

### STOP GATE 1: Entity Exists

**Check:** Does entity ID already exist?
**Pass:** ID is unique
**Fail:** STOP. Use existing entity or new ID.

### STOP GATE 2: Schema Valid

**Check:** Does YAML match schema?
**Pass:** `make validate` passes
**Fail:** STOP. Fix schema errors.

### STOP GATE 3: References Resolve

**Check:** Do all references exist?
**Pass:** `make check-refs` passes
**Fail:** STOP. Create missing entities or fix refs.

### STOP GATE 4: Bidirectional Links

**Check:** Are references bidirectional?
**Pass:** `make check-bidirectional` passes
**Fail:** STOP. Add reverse reference.

---

## Quick Reference

```
COMMANDS
make validate          # Schema validation
make check-refs        # Reference validation
make check-bidirectional  # Bidirectional links
make generate          # Regenerate docs
make impact ID=REQ-001 # Impact analysis

NEVER EDIT
generated/docs/*
generated/diagrams/*

ALWAYS EDIT
data/**/*.yaml
```

---

## Anti-Patterns

| If you're doing... | STOP. Do this instead... |
|--------------------|--------------------------|
| Editing generated/ | Edit data/*.yaml, run make generate |
| One-way reference | Add bidirectional link |
| Hardcoding schema | Use LinkML schema |
| Missing validation | Run make validate |

---

## Reference Files

- [reference/schemas.md](reference/schemas.md) - Entity schemas
- [reference/templates.md](reference/templates.md) - YAML templates
- [reference/traceability.md](reference/traceability.md) - Reference patterns