update-demo-docs

name	update-demo-docs
metadata	{"author":"rhoai3-coding-demo","version":"1.2.0","platform-family":"rhoai","platform-baseline":"repo","ocp-baseline":"repo","skill-group":"Documentation"}
description	Check and update documentation consistency after a change. Use when scripts, manifests, or demo flow change and documentation might be stale. Inspects README.md, stage READMEs, OPERATIONS.md, TROUBLESHOOTING.md, and BACKLOG.md for consistency with the current implementation. Do NOT use for writing operational docs from scratch (use demo-operations-docs skill), rewriting educational narrative (use README rules), or troubleshooting (use rhoai-troubleshoot).

Update Demo Docs

Use this skill after any behavior change to ensure documentation stays consistent with the implementation.

When to invoke

• After changing deploy scripts, validate scripts, or GitOps manifests
• After adding, removing, or modifying a demo stage
• After resolving or adding a workaround
• After changing model serving, MaaS, or gateway behavior
• After changing Dev Spaces, MTA, or Developer Hub configuration
• When a PR touches code but no docs

Documents to check

Document	Check for
README.md	Stage table accuracy, product map, trust boundaries, deploy commands
stages/NNN-*/README.md	Demo storyline continuity, architecture claims, "What This Stage Adds", "What To Notice And Why It Matters", trust boundary language
docs/OPERATIONS.md	Deployment order, validation strategy, Argo CD app names, commands
docs/TROUBLESHOOTING.md	Affected symptoms, recovery steps, diagnostic commands
BACKLOG.md	Workaround status, new limitations, resolved items

Consistency checks

1. Stage table matches reality

Verify the root README stage table matches:

• Actual directories under stages/
• Actual Argo CD applications under gitops/argocd/app-of-apps/
• Stage numbering and names

2. Deploy commands match scripts

Verify commands in README and OPERATIONS.md match what the scripts actually do.

3. Trust boundary language is accurate

After model-serving or gateway changes:

• Private model claims still hold
• External model descriptions are accurate
• MaaS role is correctly described
• MCP/tool-context boundaries are described separately from model access when relevant
• Trust Boundaries sections stay concise, preferably one paragraph
• EU AI Act language is readiness-oriented and does not claim compliance

4. Product and version references

After operator or version changes:

• Product versions in README match manifests
• Official doc links are for the correct version
• No stale version references

5. Workaround documentation

After resolving or adding a workaround:

• BACKLOG.md reflects the current state
• docs/TROUBLESHOOTING.md has relevant entries
• Workaround code has comments explaining why

6. Cross-references

• Stage READMEs link to their next stage correctly
• Operations doc references real namespaces and resource names
• Troubleshooting entries reference real commands

7. Stage README narrative style

When checking a stage README:

• The opening should lead with this repository's demo storyline, not with a summary of an external article, blog, or product document.
• Read the stage's relevant ## References links before rewriting product-positioning language, prioritizing official Red Hat product pages and documentation.
• Red Hat blogs and documentation should appear as alignment, implementation baseline, or reference material after the stage's role in the workshop is clear.
• The stage should connect the previous stage and the capability being introduced without over-emphasizing capabilities planned for later stages.
• Stage continuity should be carried by the opening narrative, architecture diagram, trust boundary, and Next Stage link rather than a dedicated Where This Fits In The Full Platform section.
• What This Stage Adds should be concise and capability-oriented, not a low-level manifest inventory.
• What This Stage Adds should normally be one short capability sentence plus four to six bullets.
• What This Stage Adds should prefer product/platform language and mention CRs or resource names only when they are important teaching concepts.
• What This Stage Adds should avoid per-bullet manifest links; the stage manifest directory belongs in Deploy And Validate.
• What This Stage Adds should avoid YAML field paths, probe timings, patch jobs, sync hooks, generated resource names, and validation behavior unless they are central to the architecture story.
• How Red Hat And Open Source Make It Work should be concise, normally one to three short paragraphs.
• How Red Hat And Open Source Make It Work should explain the Red Hat product integration pattern plus relevant upstream projects without duplicating the product and open source lists.
• How Red Hat And Open Source Make It Work should keep important support-posture or demo-deviation notes, but move operational detail to docs/OPERATIONS.md or BACKLOG.md.
• Red Hat Products Used should list only products or productized components used by the current stage.
• Red Hat Products Used should avoid downstream consumers, future-stage integrations, and products mentioned only for platform context.
• Red Hat Products Used should link product names to official Red Hat product pages when available, or official Red Hat documentation for productized components.

8. Architecture diagram consistency

When checking architecture diagrams in READMEs:

• Verify ASCII or Mermaid diagrams accurately reflect deployed components.
• Verify the three-layer structure (Hybrid Cloud Platform, Private AI Platform, Enterprise Application Platform) is consistent across stages.

Workflow

1. Identify the behavior change (from git diff or task context).
2. Check each document in the table above for staleness.
3. For each stale section, determine the correct content from manifests/scripts.
4. Update the document following its rules:
   • READMEs: educational, blog-like (.agents/rules/docs.md)
   • OPERATIONS.md: operational, copy-pastable (.agents/rules/docs.md)
   • TROUBLESHOOTING.md: symptom-driven (.agents/rules/docs.md)
   • BACKLOG.md: status tracking with removal conditions
5. Run git diff --check after edits.

Output format

## Documentation consistency check

### Changed behavior
- [describe what changed]

### Documents updated
- [list of files updated with brief description]

### Documents verified (no update needed)
- [list of files checked and confirmed current]

### Documents that could not be verified
- [any docs requiring live cluster confirmation]

What this skill must never do

• Turn READMEs into runbooks (operational content belongs in OPERATIONS.md)
• Claim capabilities that are not backed by manifests/scripts
• Remove workaround documentation without confirmed resolution
• Add operational detail to stage READMEs (use OPERATIONS.md)