Validations to Perform

Focus exclusively on the 22 semantic checks below that require language understanding and are NOT covered elsewhere.

Validations to Perform

Run each of the following checks against the documentation provided. For each check, report a pass/fail/warn with specific findings.

A. Source Grounding & Hallucination Detection (Non-ADR Docs)

1. Code Reference Accuracy (All Non-ADR Docs)

• For every file path, function name, package name, and component name mentioned in AGENTS.md, ARCHITECTURE.md, concept docs, workflow docs, and component docs, verify it actually exists in the target repository
• Flag references to files, directories, functions, or types that do not exist
• Pay special attention to critical code locations tables, component entry points, and "Location in Code" sections
• This check applies to ALL doc types except ADRs (handled by validate-adr skill check 10)

2. Concept Definition Accuracy

• For each concept doc under agentic/domain/concepts/, read the underlying CRD, type definition, or package in the target codebase
• Verify the concept doc's definition, purpose, lifecycle, and key fields match the actual code behavior
• Flag definitions that are vague, incorrect, or describe behavior the code does not exhibit
• Check that "Key Fields / Properties" sections document fields that actually exist on the type

3. Component Boundary Accuracy

• Verify that ASCII diagrams and component relationship tables in AGENTS.md and ARCHITECTURE.md reflect actual code structure
• Cross-reference against import graphs, package dependencies, and controller registrations in the target repo
• Flag diagrams that show relationships that don't exist in code, or omit significant real relationships
• Check that the "Component Boundaries" section in AGENTS.md matches the components table in ARCHITECTURE.md

B. Content Quality & Minimalism Compliance

4. Narrative Detection (Semantic)

• Beyond what prose ratio (deterministic) catches, detect explanatory narrative disguised as structured content
• Flag bullet-pointed paragraphs, table cells with multi-sentence explanations, and list items that are actually prose paragraphs
• ARCHITECTURE.md should be tables and structured lists with minimal prose -- flag any "The system works by..." style content even if formatted as bullets
• AGENTS.md should be navigation pointers, not explanations -- flag any section that explains rather than links
• Reference: Rules 13, 39 from the agentic-docs-guide

5. Content Duplication Across Docs

• Detect when the same information is substantively repeated across multiple files, even when paraphrased differently
• Common duplication patterns: same component description in AGENTS.md, ARCHITECTURE.md, AND the component doc; same concept explained in glossary AND concept doc AND workflow doc
• The correct pattern is: define once in the detailed doc, link from elsewhere with a one-line summary
• Flag the duplicated content and recommend which file should be the single source of truth
• Reference: Rule 38

6. Prescriptive vs. Descriptive Language

• Detect "always use X", "never do Y", "you must", "you should" instructions that tell readers what to do
• The correct pattern is documenting what the codebase does and why (patterns with rationale), not prescribing behavior
• Exception: Key Invariants in AGENTS.md are intentionally prescriptive -- do not flag those
• Flag prescriptive content and suggest descriptive alternatives
• Reference: Rule 40

7. README/Existing-Docs Duplication

• Compare generated agentic docs against the target repo's README.md, CONTRIBUTING.md, and docs/ directory
• Flag when agentic docs duplicate content already present in existing documentation, even when reworded
• The correct pattern is: link to existing docs with See: [existing doc](path) rather than restating
• Reference: Rule 41

8. Unnecessary Tutorial/Example Content

• Detect step-by-step tutorials, exhaustive code examples (more than 1-2 canonical examples), or verbose walkthroughs
• Distinguish between: a concise canonical example (acceptable) vs. an exhaustive walkthrough (not acceptable)
• Flag content that belongs in docs/ or a wiki rather than agentic/ docs
• Reference: Rules 42-43

9. Token Efficiency Assessment

• Evaluate whether each doc provides unique value proportional to its length
• Flag docs where significant portions could be removed without losing information useful to an AI agent
• Consider: would a coding agent benefit from this content when assembling a context bundle, or is it filler?
• Flag verbose sections and suggest concise alternatives
• Reference: Rule 44

C. Cross-Document Semantic Consistency

10. Glossary-Concept Doc Alignment

• For each term in agentic/domain/glossary.md that has a corresponding concept doc, compare the definitions
• Flag semantic mismatches where the glossary says one thing but the detailed concept doc says something different
• The glossary definition should be a faithful 1-2 sentence summary of the concept doc, not a contradicting or divergent description

11. Terminology Consistency (Corpus-Wide)

• Check that the same concepts are referred to by the same names across ALL document types
• Scan AGENTS.md, ARCHITECTURE.md, concept docs, workflow docs, component docs, exec-plans, glossary, and top-level agentic files
• Flag inconsistent naming without established aliases (e.g., switching between "MCD", "MachineConfigDaemon", and "the daemon" without defining equivalence in glossary or frontmatter)
• This extends beyond what validate-adr checks (which is ADR-internal and ADR-to-glossary only)

12. Component-Workflow Coherence

• For each workflow doc, verify that the roles described for each component match what the component's own doc says
• Flag cases where a workflow assigns a responsibility to a component that the component doc does not list
• Check that component names, entry points, and behaviors are consistent between workflow and component docs

13. Index File Content Accuracy

• For each index.md file, verify that the descriptions and categorizations of linked documents match their actual content
• Flag cases where: an index describes a doc differently than its actual scope, a doc is categorized incorrectly, or an index description is stale relative to the current doc content
• Check that ADR status in decisions/index.md matches the status field in each ADR's frontmatter

D. Execution Plan Quality

14. Goal Clarity and Measurability

• Assess whether each exec-plan has a specific, concrete goal with measurable success criteria
• Flag vague goals (e.g., "improve performance") vs. specific ones (e.g., "reduce reconciliation latency p95 from 5s to 2s")
• Success criteria should be checkboxes with observable outcomes, not aspirational statements

15. Plan-Codebase Alignment

• Verify that exec-plans reference actual components, code paths, packages, and realistic implementation phases for the target repository
• Flag plans that describe work on components or systems that don't exist in the codebase
• Check that "Architecture Changes" and "Technical Approach" sections are grounded in the real codebase

16. Plan Completeness

• Assess whether each exec-plan covers required sections with substantive content, not boilerplate
• Required sections with substance: Goal, Context, Technical Approach, Implementation Phases, Testing Strategy
• Flag sections that are copied verbatim from the template without customization
• Flag plans where implementation phases are generic (e.g., "Phase 1: Planning, Phase 2: Implementation") rather than specific to the work

E. Repo-Specific Content Relevance

17. OpenShift-Specific Marker Accuracy

• For OpenShift repositories only: verify glossary term markers are correctly applied
• 🔴 should mark genuinely OpenShift-specific terms (not found in vanilla Kubernetes)
• ⚫ should mark Kubernetes core concepts (exist in any Kubernetes cluster)
• 🟡 should mark extended ecosystem terms (not core K8s, not OpenShift-only)
• Flag misclassified terms with reasoning

18. Enhancement-ADR Linkage Accuracy

• For OpenShift repositories: verify that ADR enhancement-refs fields point to the correct OpenShift enhancement proposals
• Cross-reference the ADR's decision content against the referenced enhancement to confirm they address the same topic
• Flag linkages where the enhancement proposal covers a different topic than the ADR

19. Core Beliefs Relevance

• Assess whether agentic/design-docs/core-beliefs.md contains principles actually evidenced in the codebase
• Flag generic software engineering platitudes not specific to this repo (e.g., "we value clean code", "we believe in testing")
• Good core beliefs reference specific patterns, constraints, or design choices visible in the code (e.g., "we enforce single-owner reconciliation to prevent write conflicts, validated by admission webhook at pkg/webhooks/validate.go")
• Check that each principle's "Example in this repo" field references real code

F. AGENTS.md Functional Assessment

20. Navigation Path Completeness

• Test each "Quick Navigation by Intent" section in AGENTS.md against common developer intents:
  • "I need to understand the system" -- does the path lead to architecture and design docs?
  • "I'm implementing a feature" -- does the path lead to design, development, and testing docs?
  • "I'm fixing a bug" -- does the path lead to component map, debugging, and tests?
  • "I need to understand a concept" -- does the path lead to glossary and concept docs?
• Flag intents where the navigation path is incomplete, misleading, or leads to docs that don't address the intent
• This is NOT link validity (deterministic) -- this is whether the linked docs actually serve the stated intent

21. Repo Description Accuracy

• Verify that the 1-2 sentence repo description in AGENTS.md's "What This Repository Does" section accurately captures what the repository actually does
• Cross-reference against the repo's actual code, README.md, and go.mod/package.json
• Flag descriptions that are inaccurate, too vague to be useful, or describe what the repo aspires to be rather than what it is

22. Invariants Accuracy

• For each item in the "Key Invariants (ENFORCE THESE)" section of AGENTS.md, verify it is actually enforced in the codebase
• Check for enforcement via: tests, admission webhooks, linting rules, CI checks, or code-level assertions
• Flag invariants that are aspirational rather than enforced (no enforcement mechanism found)
• Flag the "Validated by" field if it claims an enforcement mechanism that doesn't exist

Output Format

Produce a structured report with:

## Content Semantic Validation Report

### Summary
- Documents validated: [count]
- Total checks run: 22
- Passed: X
- Failed: Y
- Warnings: Z

### Category Results

#### A. Source Grounding & Hallucination Detection
- Checks 1-3: [X passed, Y failed, Z warnings]

#### B. Content Quality & Minimalism Compliance
- Checks 4-9: [X passed, Y failed, Z warnings]

#### C. Cross-Document Semantic Consistency
- Checks 10-13: [X passed, Y failed, Z warnings]

#### D. Execution Plan Quality
- Checks 14-16: [X passed, Y failed, Z warnings]

#### E. Repo-Specific Content Relevance
- Checks 17-19: [X passed, Y failed, Z warnings] (or N/A if not OpenShift)

#### F. AGENTS.md Functional Assessment
- Checks 20-22: [X passed, Y failed, Z warnings]

### Detailed Findings

#### [Check Number]. [Check Name] - PASS/FAIL/WARN
- **Issue**: [description]
- **Evidence**: [quote from the doc that demonstrates the issue]
- **Affected file(s)**: [list of files]
- **Recommendation**: [specific fix]

### Cross-Document Findings
[Any issues that span multiple documents, such as terminology inconsistency or content duplication]

### Priority Fixes
[Ordered list of the most impactful issues to fix first, with file path and check number]