nextura-frontmatter-schema

Original source / Raw SKILL.md

---
name: nextura-frontmatter-schema
scope: nextura
description: >
  Standard metadata structure for data files. Covers YAML SSOT entities
  and markdown frontmatter. Defines required fields, validation, and
  schema patterns for structured content.
version: 3.0.0
triggers:
  - frontmatter
  - markdown metadata
  - yaml header
  - document schema
  - structured content
---

# Frontmatter & Schema Standards

You are defining structured metadata for data files. Consistent schemas enable
automation, validation, and traceability. Every data file should have
machine-readable structure.

**Your goal**: Standardized, validated schemas across all data files.

---

## Two Schema Paradigms

### When to Use Which

| Paradigm | Use When | Examples | Location |
|----------|----------|----------|----------|
| **YAML SSOT** | Data is primary, relationships matter, traceability required | Requirements, Components, Decisions | `data/{type}/` |
| **Markdown Frontmatter** | Prose is primary, human readability, standalone content | Guides, Runbooks, Meeting notes | `docs/{category}/` |

---

## Core Entity Structure (YAML SSOT)

All YAML SSOT entities share this structure:

```yaml
# IDENTITY - What is this?
id: "entity-id"              # Unique, kebab-case
type: "entity-type"          # requirement | component | decision | etc.

# CONTENT - What does it say?
title: "Human Readable Title"
description: |
  Detailed description of the entity.

# CLASSIFICATION - How is it categorized?
status: "draft"              # draft | approved | current | deprecated

# TRACEABILITY - What does it connect to?
# (varies by entity type)

# OWNERSHIP - Who is responsible?
owner: "team-name"
```

**For detailed entity schemas:** See [reference/yaml-ssot-schemas.md](reference/yaml-ssot-schemas.md)

---

## Entity Type Quick Reference

| Type | Location | Key Fields |
|------|----------|------------|
| requirement | `data/requirements/` | category, priority, level, statement |
| component | `data/components/` | c4_level, c4_type, technology, relationships |
| vendor | `data/vendors/` | vendor, integration, used_by |
| decision | `data/decisions/` | context, options, decision, consequences |
| flow | `data/flows/` | actors, steps, alternatives |

---

## ID Conventions

```
Format: {prefix}-{identifier}

Requirements:  REQ-ONB-001, REQ-AUTH-001
Components:    onboarding-service, api-gateway
Vendors:       kyc-provider, payment-gateway
Decisions:     ADR-001, ADR-002
Flows:         customer-onboarding, payment-processing
```

---

## Traceability Fields

| Field | Direction | Used In | Links To |
|-------|-----------|---------|----------|
| `derived_from` | upstream | requirement | sources |
| `traces_to` | downstream | requirement | components |
| `satisfies` | upstream | component | requirements |
| `informed_by` | upstream | component | decisions |
| `affects` | downstream | decision | components |

**Bidirectional Rule:** When A references B, B MUST reference A back.

**For full traceability reference:** See [reference/traceability.md](reference/traceability.md)

---

## STOP GATES

### STOP GATE 1: ID Unique and Valid

**Check:** Is the ID unique and follows convention?
**Pass:** ID matches pattern, doesn't exist elsewhere
**Fail:** STOP. Fix ID format or resolve duplicate.

### STOP GATE 2: Required Fields Present

**Check:** Are all required fields present?
**Pass:** Schema validation passes
**Fail:** STOP. Add missing fields.

### STOP GATE 3: References Resolve

**Check:** Do all references point to existing entities?
```bash
make check-refs
```
**Pass:** All references valid
**Fail:** STOP. Fix broken references.

### STOP GATE 4: Bidirectional Links

**Check:** Are bidirectional references in place?
```bash
make check-bidirectional
```
**Pass:** All links are bidirectional
**Fail:** STOP. Add missing reverse references.

---

## Validation Commands

```bash
make validate            # Pydantic schema validation
make check-refs          # Reference validation
make check-bidirectional # Bidirectional link check
make check               # All validation checks
```

---

## Quick Reference Checklists

```
YAML SSOT ENTITY:
[ ] id: unique, kebab-case or PREFIX-XXX format
[ ] type: matches directory (requirements -> requirement)
[ ] title: human-readable name
[ ] status: valid lifecycle state
[ ] Traceability fields populated
[ ] Bidirectional references added
[ ] File in correct directory
[ ] Filename matches id

MARKDOWN FRONTMATTER:
[ ] id: unique doc identifier
[ ] type: document type (guide, runbook, spec)
[ ] title: page title
[ ] created_at: ISO 8601 timestamp
[ ] status: lifecycle status
[ ] owner: responsible team/person
```

---

## Anti-Patterns

| If you're doing... | STOP. Do this instead... |
|--------------------|--------------------------|
| Prose in YAML | Use description field only |
| Data in markdown | Use YAML SSOT for structured data |
| No type field | Always include type matching directory |
| One-way references | Add bidirectional links |
| Duplicate IDs | Ensure uniqueness across all files |
| Missing validation | Run `make check` before commit |

---

## Reference Files

- [reference/yaml-ssot-schemas.md](reference/yaml-ssot-schemas.md) - Full entity schemas
- [reference/markdown-frontmatter.md](reference/markdown-frontmatter.md) - Markdown frontmatter schema
- [reference/traceability.md](reference/traceability.md) - Traceability field reference


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### reference/yaml-ssot-schemas.md

```markdown
# YAML SSOT Entity Schemas

Detailed schema definitions for YAML SSOT entities.

---

## Requirement (ISO 29148)

```yaml
id: REQ-XXX
type: requirement

# Classification
category: functional          # functional | non-functional | constraint
priority: must               # must | should | could | wont
level: system                # business | stakeholder | system | component

# Content
title: "Short descriptive title"
statement: |
  The system SHALL [do something specific].

acceptance_criteria:
  - given: "precondition"
    when: "action"
    then: "expected result"

# Traceability
derived_from: []             # Upstream: business needs, regulations
traces_to: []                # Downstream: components, decisions

# Metadata
source: "Document or stakeholder"
owner: team-name
status: draft                # draft | approved | implemented | verified
```

---

## Component (C4 Model)

```yaml
id: component-name
type: component

# C4 Classification
c4_level: container          # context | container | component
c4_type: container           # person | system | container | component

# Identity
title: "Human Readable Name"
description: |
  What this component does.

# Technical
technology:
  - "Python/FastAPI"
  - "PostgreSQL"
owner: team-name
repo: github.com/org/repo

# Relationships
relationships:
  - target: other-component
    description: "Sends data to"
    protocol: REST
    async: false

# Interfaces
interfaces:
  - type: REST
    spec: "./api/spec.yaml"

# Traceability
satisfies:                   # Requirements this implements
  - REQ-XXX
informed_by:                 # Decisions that shaped this
  - ADR-XXX

status: current              # current | deprecated
```

---

## Decision (MADR)

```yaml
id: ADR-XXX
type: decision

title: "Decision Title"
date: 2024-01-15
status: accepted             # proposed | accepted | deprecated | superseded

context: |
  Why we need to make this decision.

drivers:
  - "Driver 1"
  - "Driver 2"

options:
  - id: option-1
    title: "Option Name"
    pros:
      - "Pro 1"
    cons:
      - "Con 1"

decision: option-1
rationale: |
  Why we chose this option.

consequences:
  positive:
    - "Good outcome"
  negative:
    - "Trade-off"
  mitigations:
    - "How we address negatives"

# Traceability
addresses:                   # Requirements this addresses
  - REQ-XXX
affects:                     # Components affected
  - component-name

supersedes: null
superseded_by: null
```

---

## Vendor

```yaml
id: vendor-name
type: vendor

title: "Vendor Name (Company)"
description: |
  What this vendor provides.

vendor:
  name: "Company Legal Name"
  contract_id: "CONTRACT-XXX"
  support_contact: [email protected]
  sla: "99.9% uptime"

integration:
  protocol: REST
  auth: OAuth2
  base_url: https://api.vendor.com/v1
  spec: "./api/vendor-api.yaml"
  limits:
    requests_per_second: 100

# Traceability
used_by:
  - component-name
satisfies:
  - REQ-XXX

status: current
```

---

## Flow

```yaml
id: flow-name
type: flow

title: "Flow Title"
description: |
  What this flow represents.

actors:
  - id: customer
    type: person
  - id: service-name
    type: system

steps:
  - order: 1
    from: customer
    to: service-name
    action: "Submits request"
    data: "Request payload"
    async: false

alternatives:
  - name: "Error Path"
    trigger: "When validation fails"
    steps:
      - order: 1
        from: service-name
        to: customer
        action: "Return error"

# Traceability
implements:
  - REQ-XXX
involves:
  - service-name
```

```

### reference/traceability.md

```markdown
# Traceability Fields

Reference for traceability links between entities.

---

## Reference Field Summary

| Field | Direction | Used In | Links To |
|-------|-----------|---------|----------|
| `derived_from` | upstream | requirement | sources, requirements |
| `traces_to` | downstream | requirement | components, decisions |
| `satisfies` | upstream | component, vendor | requirements |
| `informed_by` | upstream | component | decisions |
| `addresses` | upstream | decision | requirements |
| `affects` | downstream | decision | components |
| `implements` | upstream | flow | requirements |
| `involves` | association | flow | components |
| `used_by` | inbound | vendor | components |

---

## Bidirectional Rules

When A references B, B should reference A:

```
If A has...          | Then B should have...
---------------------|------------------------------------
traces_to: [B]       | satisfies: [A] (if B is component)
satisfies: [B]       | traces_to: [A] (if B is requirement)
affects: [B]         | informed_by: [A]
addresses: [B]       | traces_to: [A]
```

---

## Quick Reference

```
Requirement -> Component: traces_to / satisfies
Requirement -> Decision:  traces_to / addresses
Decision -> Component:    affects / informed_by
Component -> Vendor:      relationships.target / used_by
Flow -> Requirement:      implements
Flow -> Component:        involves
```

---

## Validation Commands

```bash
# Check all references resolve
make check-refs

# Check bidirectional links
make check-bidirectional

# Full validation suite
make check
```

```

### reference/markdown-frontmatter.md

```markdown
# Markdown Frontmatter Schema

Schema for markdown document frontmatter.

---

## Base Frontmatter

```yaml
---
# IDENTITY
id: "doc-001"
type: "guide"
title: "Getting Started Guide"

# PROVENANCE
created_at: "2024-01-15T10:30:00Z"
created_by: "[email protected]"

# CLASSIFICATION
domain: "onboarding"
tags: ["quickstart", "tutorial"]

# LIFECYCLE
status: "approved"

# GOVERNANCE
owner: "docs-team"
---

# Getting Started

Content goes here...
```

---

## Document Types

| Type | Purpose | Required Fields |
|------|---------|-----------------|
| guide | How-to documentation | title, domain, status |
| runbook | Operational procedures | title, domain, owner |
| note | Meeting notes, memos | title, created_at |
| spec | Technical specifications | title, version, status |

---

## Frontmatter Validation

```python
import frontmatter
from pydantic import BaseModel, Field
from datetime import datetime

class BaseFrontmatter(BaseModel):
    id: str = Field(..., pattern=r"^[a-z]+-\d+$")
    type: str
    title: str
    created_at: datetime
    created_by: str
    domain: str
    status: str
    owner: str

def validate_markdown(path: Path) -> bool:
    post = frontmatter.load(path)
    fm = BaseFrontmatter(**post.metadata)
    return True
```

---

## File Organization

```
docs/
├── guides/                 # How-to guides
│   └── getting-started.md
├── runbooks/               # Operational docs
│   └── incident-response.md
└── specs/                  # Technical specs
    └── api-design.md
```

```