oci-deal-accelerator/kb/README.md

Knowledge Base — Contributor Guide

The KB is the moat. It encodes Oracle field experience, OCI service quirks, and architecture patterns that aren't in the official docs. Tools and the skill itself read these YAMLs at runtime.

Directory map

Directory	Purpose	Format
services/	One file per OCI service. Capabilities, limits, gotchas, when-to-use.	Frontmatter + structured body
patterns/	Composable architecture blocks (HA, DR, hub-spoke, RACI, ECAL artefacts).	Frontmatter + body, often nested dirs
sizing/	CPU/memory/storage conversion ratios, IOPS limits, scaling rules.	Body only
pricing/	oci-sku-catalog.yaml (200+ SKUs, auto-refreshed) + compute.yaml (shape-level, auto-refreshed). Both pull from the Oracle public pricing API.	Frontmatter + body
competitive/	OCI vs AWS / Azure / GCP service mapping and objection handling.	Frontmatter + body
compatibility/	Feature matrices (e.g. ADB-S features). Currently thin — expected to grow.	Frontmatter + body
well-architected/	5-pillar checklists, landing zone patterns, persona views.	Frontmatter + body
architecture-center/	Auto-curated index of Oracle Architecture Center reference architectures.	Single catalog.yaml
field-knowledge/	Real-world gotchas, lessons learned, undocumented limits.	Frontmatter + body
field-findings/	Tracker of newly logged field issues with confidence decay.	Single tracker.yaml
diagram/	OCI icon libraries, native PPTX icon index, and reference layouts for diagram generation.	Mixed

Required frontmatter

Every YAML file under kb/ should start with a frontmatter block:

---
last_verified: 2026-04-08            # YYYY-MM-DD, when the file was last reviewed against current Oracle docs
source: https://docs.oracle.com/...  # primary source(s) used during last verification
description: One-line summary of what this file contains
---

# body starts here
key: value

The freshness checker (tools/kb_freshness.py) reads last_verified and warns if a file is older than the thresholds in config/kb-governance.yaml (default: warning at 180 days, stale at 365 days). The KB linter (tools/kb_linter.py) accepts last_updated and last_refreshed as fallback field names but new files should use last_verified.

How to add a new service card

1. Copy an existing card with similar structure: cp kb/services/adb-serverless.yaml kb/services/<your-service>.yaml.
2. Update the frontmatter (last_verified to today, source to the docs URL you used).
3. Fill in fields. Keep gotchas honest — if the service has a limitation, write it down. The KB's value is honesty, not marketing.
4. Run python tools/kb_linter.py and fix any issues it reports for your file.
5. Run make freshness to confirm your new file is FRESH.

How to add a pattern

Patterns can be either single-file (e.g. kb/patterns/business-drivers.yaml) or directory-based for larger blocks (e.g. kb/patterns/database-ha/). Use a directory when you need multiple files (pattern + diagrams + ADRs).

Refresh tooling

File	Refresh tool
kb/pricing/oci-sku-catalog.yaml	python tools/refresh_sku_catalog.py --refresh (Oracle pricing API)
kb/pricing/compute.yaml	python tools/refresh_sku_catalog.py --refresh-domain compute (same API, shape-level)
kb/architecture-center/catalog.yaml	python tools/refresh_arch_catalog.py --whats-new (web crawl)
kb/diagram/assets/OCI_Icons.pptx + kb/diagram/oci-pptx-icons-index.json	python tools/refresh_pptx_icon_index.py [--source /path/to/OCI_Icons.pptx]
Other kb/pricing/<domain>.yaml	Not yet automated. Add a new entry to DOMAIN_REGISTRY in tools/refresh_sku_catalog.py and write a domain-specific refresher (see refresh_compute_yaml as a template).
Everything else	Manual — review against Oracle docs, bump last_verified

The shortcut for everyone:

make freshness            # report stale files
make freshness-refresh    # run automatic refreshes for files that support them
make pptx-icons-refresh   # sync new OCI_Icons.pptx revision + rebuild manifest/index

For native PowerPoint diagram generation, the repo now carries a bundled kb/diagram/assets/OCI_Icons.pptx plus a derived manifest/index. If Oracle publishes a newer icon deck, replace it or point the refresh tool at the new file and rebuild:

make pptx-icons-refresh
python tools/refresh_pptx_icon_index.py --source ~/Downloads/OCI_Icons.pptx

Architecture Center native benchmark

This repo now has a fixed, reusable benchmark path for Oracle Architecture Center visual fidelity. Keep this workflow stable because future sessions must re-run it exactly, not reconstruct it from memory.

Primary validation method:

• draw.io fidelity is measured by exporting the generated *-rebuilt.drawio with the real draw.io binary and comparing that PNG against the official Architecture Center PNG.
• In this WSL setup, the primary binary is /mnt/c/Program Files/draw.io/draw.io.exe.
• Only if the draw.io CLI is unavailable or fails should the runner fall back to the official bundled SVG companion.
• Native .pptx fidelity is measured by rasterizing the editable PPTX slide with tools/oci_pptx_render.py. Do not depend on soffice or LibreOffice.

Operational notes that must remain persisted:

• Many official Oracle .drawio files are compressed inside <diagram> as base64 + raw-deflate XML. Extraction and validation must support that form.
• tools/drawio_visual_validator.py is a structural gate before raster diff: it catches giant fonts, duplicate ids, off-canvas geometry, and dangling edges, including in compressed official .drawio files.
• tools/oci_pptx_render.py is intentionally tolerant of unsupported WMF/EMF media. It skips those assets, records them in skipped_media, and keeps the benchmark running instead of aborting the case.

Standard rerun command:

make archcenter-benchmark-20

Equivalent explicit command:

.venv/bin/python tools/oci_archcenter_batch.py \
  --limit 20 \
  --threshold 0.82 \
  --fidelity-threshold 0.90 \
  --output-root examples/eval-2026-04-25-archcenter-native-20-v8

Acceptance contract:

• Official page + ZIP assets staged per case
• Editable drawio rebuilt successfully
• draw.io CLI fidelity PASS against official PNG, or documented SVG fallback
• Icon-cluster coverage >= 0.55
• Native PPTX generated with no unresolved or oversize icon refs
• Native PPTX raster fidelity PASS against official PNG
• Evidence written under each case: reference assets, generated outputs, raster renders, diff images, JSON summaries, and markdown reports

Latest verified run:

• examples/eval-2026-04-25-archcenter-native-20-v8
• considered=28, processed=20, skipped=8, PASS=20, FAIL=0
• The verified pool currently has no open native benchmark failures. The remaining gaps are confined to the skipped pool, which is still filtered out for annotation-heavy diagrams or missing draw.io icon families such as DNS/VPN/maximum-security-zone variants.

Pricing files

There are exactly two pricing files, both auto-refreshed from the Oracle public pricing API:

1. kb/pricing/oci-sku-catalog.yaml — 200+ SKUs across 20 categories (compute, storage, database, networking, observability, security, AI/ML, GenAI, etc.). Refresh: python tools/refresh_sku_catalog.py --refresh.
2. kb/pricing/compute.yaml — shape-level estimation pricing (VM.Standard.E5.Flex hourly, monthly, etc.). Different abstraction from the SKU catalog — useful for SA estimation. Refresh: python tools/refresh_sku_catalog.py --refresh-domain compute.

Pricing context that ISN'T a price (billing models, BYOL rules, free tiers, service nuances, hyperscaler comparisons) lives in kb/field-knowledge/pricing-knowledge.yaml. That file is non-numeric where possible and does not need API refresh.

There are no other pricing files. The previous kb/pricing/database.yaml, storage.yaml, networking.yaml, etc. were removed on 2026-04-08 — their prices were drift-prone and 30-800% off the live API; their notes were migrated to kb/field-knowledge/pricing-knowledge.yaml.

Linter

python tools/kb_linter.py                # all checks
python tools/kb_linter.py --show-decay   # confidence decay only
python tools/kb_linter.py --check-tags   # tag taxonomy only
python tools/kb_linter.py --check-owners # domain owner assignments only

The linter reports STALE / WARNING for files past their freshness threshold, unknown tags in field findings, and missing domain owners. Exit code is 1 if any issues are found.

Review cadence

• Field findings: confidence decays automatically — see config/kb-governance.yaml
• Service cards: review at least every 6 months, or when Oracle publishes a major update
• Patterns: review at least once a year
• Pricing: ideally every quarter — Oracle changes prices ~2x per year for major SKUs

Thin directories

compatibility/ and field-findings/ currently hold a single file each. Both are expected to grow as more SAs contribute. If after 6 months they remain at 1 file, consider consolidating with a parent directory.