vibe-docs

# Vibe-Docs Skill

Semantic validation for documentation - verifies claims match deployment reality.

## Overview

**Structure vs Semantic:**
- `/doc` validates STRUCTURE (links, coverage, sections)
- `/vibe-docs` validates TRUTH (do claims match reality?)

**When to Use:**
- After deployment changes
- Before releases
- When docs feel "stale"
- Periodic audits (monthly)

---

## Commands

| Command | Action |
|---------|--------|
| `status` | Check status claims against deployment |
| `agents` | Verify agent catalog matches cluster |
| `images` | Verify IMAGE-LIST matches registry |
| `full` | Run all checks |

---

## Phase 1: Gather Claims

Extract claims from documentation:

```bash
# Status claims
grep -r "Current Status:" docs/code-map/ | grep -E "RUNNING|FAILED|DEPLOYED"

# Agent claims
grep -E "✅ Deployed|✅ Ready|DEPLOYED" docs/

# Image claims
grep -E "image:|Image:" charts/*/IMAGE-LIST.md
```

---

## Phase 2: Gather Reality

Query deployment state:

### For Agents (KAgent)

```bash
# Get all agents and their status
oc get agents.kagent.dev -n ai-platform -o json | \
  jq -r '.items[] | "\(.metadata.name): \(.status.conditions[0].status)"'
```

### For Pods/Services

```bash
# Get running pods
oc get pods -n ai-platform -o json | \
  jq -r '.items[] | select(.status.phase=="Running") | .metadata.name'
```

### For Images

```bash
# Get deployed images
oc get pods -n ai-platform -o json | \
  jq -r '.items[].spec.containers[].image' | sort -u
```

---

## Phase 3: Compare

Cross-reference claims vs reality:

### Mismatch Categories

| Category | Severity | Example |
|----------|----------|---------|
| **False Positive** | CRITICAL | Doc says RUNNING, pod doesn't exist |
| **False Negative** | HIGH | Pod running, doc says PLANNED |
| **Stale Date** | MEDIUM | Validation date > 30 days old |
| **Missing Validation** | LOW | Status without date |

### Output Format

```
===================================================================
              DOCUMENTAT