RCA-2026-02-26: Missing Antora Attributes

Executive Summary

Documentation build produced 6 "skipping reference to missing attribute" warnings. Root cause: Document written using assumed attribute names without first verifying they exist in antora.yml.

Timeline

Time Event

2026-02-26 18:58

User runs make, observes 6 attribute warnings

2026-02-26 18:59

User reports: "we keep on overlooking this"

2026-02-26 19:05

Fix: 5 attribute aliases added to antora.yml

2026-02-26 19:12

Build verified clean

Problem

Build output:

[WARN] skipping reference to missing attribute: wazuh-manager-vip
[WARN] skipping reference to missing attribute: kvm-01-ip
[WARN] skipping reference to missing attribute: ipa-01-ip
[WARN] skipping reference to missing attribute: keycloak-01-ip
[WARN] skipping reference to missing attribute: ad-dc-ip

Root Cause Analysis

5 Whys

Why # Answer

1

Why warnings? Document used 10.50.1.100 but antora.yml has kvm-ip

2

Why wrong name? Assumed -01- suffix was standard convention

3

Why wrong assumption? Existing attributes inconsistent (some have suffix, some don’t)

4

Why wasn’t antora.yml checked? Time pressure

5

Why no build before commit? No enforced pre-commit hook

Root Cause: Violated mandatory attribute verification rule by writing AsciiDoc with assumed attribute names without first running grep against antora.yml.

Resolution

Added Attribute Aliases

# antora.yml additions
wazuh-manager-vip: 10.50.1.134    # Alias for wazuh-api-vip
ad-dc-ip: 10.50.1.50              # Alias for homedc-ip
keycloak-01-ip: 10.50.1.80        # Alias for keycloak-ip
ipa-01-ip: 10.50.1.100            # Alias for ipa-ip
kvm-01-ip: 10.50.1.99             # Alias for kvm-ip

CLI Mastery: Attribute Verification

Before Writing: Verify Attribute Exists

# Search for attribute pattern
grep -i "kvm" docs/asciidoc/antora.yml

# List all IP attributes
grep -E "^\s+\w+-ip:" docs/asciidoc/antora.yml | awk -F: '{print $1}' | sort

After Writing: Find Undefined Attributes

make 2>&1 | grep "missing attribute" | awk -F': ' '{print $NF}' | sort -u

Bulk Attribute Audit

# Check all attributes in document against antora.yml
grep -oE '\{[a-z0-9-]+\}' document.adoc | \
  tr -d '{}' | sort -u | while read attr; do
    grep -q "^\s*${attr}:" docs/asciidoc/antora.yml && \
      echo "✓ $attr" || echo "✗ $attr MISSING"
  done

Prevention

Mandatory Pre-Write Checklist

  • grep antora.yml for attribute before using it

  • If attribute doesn’t exist, add it first

  • Run make before committing

  • Check for 0 warnings

Shell Function

# Add to .bashrc/.zshrc
attr-check() {
  local attr="$1"
  grep -q "^\s*${attr}:" docs/asciidoc/antora.yml && \
    echo "✓ $attr exists" || echo "✗ $attr MISSING - add to antora.yml"
}

Key Lessons

Issue Prevention

Assumed attribute names

Always grep antora.yml before using any attribute

No build verification

Run make before every commit

Inconsistent naming

Use aliases for both patterns (with/without -01-)

Time pressure

Discipline over speed - 5 seconds prevents 15 minutes

Metadata

Field Value

RCA ID

RCA-2026-02-26-001

Author

Evan Rosado

Date

2026-02-26

Status

Final

Category

Documentation / Build