forked from diegoecab/oci-deal-accelerator
ca93a0aa4e
Why this set of changes:
- KB pricing was drifting silently — domain files (database.yaml,
storage.yaml, etc.) had prices 30-800% off the live Oracle API and
nobody read them. The skill was auditing as stale on every check
with no path to fix it.
- The skill itself violated Anthropic's spec (`name` field had
uppercase/spaces) and was over the 500-line guideline (647 lines),
hurting discovery and load performance.
- Welcome flow occasionally improvised the menu instead of reading
SKILL.md, missing options.
Pricing — single source of truth, fully automated:
- Extend tools/refresh_sku_catalog.py with --refresh-domain compute,
pulls shape-level prices from the Oracle public pricing API
(apexapps.oracle.com), preserves manual fields (notes, GPU specs,
free-tier annotations, estimation_helpers), recomputes derived
monthly values, and protects $0 free-tier prices from overwrite.
- Delete 12 redundant pricing/<domain>.yaml files. They duplicated
oci-sku-catalog.yaml with worse abstractions and were nobody's
source of truth (no tool consumed them).
- Migrate the genuinely valuable knowledge from those 12 files
(billing models, BYOL rules, free-tier rules, ECPU vs OCPU,
X11M elastic model, hyperscaler comparisons, service nuances)
into kb/field-knowledge/pricing-knowledge.yaml — non-numeric,
no refresh needed.
- Result: pricing freshness check goes from 13 stale files to 0.
KB freshness automation:
- Add tools/kb_freshness.py — wrapper around kb_linter.check_freshness()
with --check, --auto-refresh, --json, --quiet modes. Bridges stale
files to their refresh tools (SKU catalog, compute domain, arch
center). Wired into the welcome flow as a pre-flight banner that
asks the user before refreshing.
- Fix pre-existing kb_linter bug: it crashed on the 45 multi-doc
YAML files (frontmatter + body pattern) because it used safe_load
instead of safe_load_all. Freshness check was effectively dead.
- Standardize timestamp field: linter now accepts last_verified,
last_updated, and last_refreshed; refresh_arch_catalog writes
last_verified instead of last_refreshed.
- Add make freshness / make freshness-refresh targets.
Skill alignment with Anthropic Agent Skills best practices:
- Rename `name: OCI Deal Accelerator` to `oci-deal-accelerator`
to comply with the [a-z0-9-]{1,64} spec.
- Refactor SKILL.md from 674 to 445 lines via progressive disclosure:
extract WA review output format, ECAL readiness format, and output
conventions into docs/skill/*.md referenced from the main file.
- Add scripts/sync-skill.py + make sync-skill: source of truth is
root SKILL.md, .agents/skills/oci-deal-accelerator/SKILL.md is
auto-generated. make lint validates sync.
- Add evaluations/ with 3 manual baseline scenarios (welcome-flow,
full-proposal, wa-review) per the Anthropic best-practices guidance
to "build evaluations first."
Welcome flow hardening:
- Tighten CLAUDE.md to MANDATE reading SKILL.md before showing the
menu (no improvising), and document the freshness pre-flight check
with the ask-before-refresh user flow.
- Update SKILL.md welcome flow to instruct: parse kb_freshness JSON,
show banner with stale count + oldest file, prompt user to refresh
(only when an automated tool exists), fall back silently on errors.
Linter hygiene (zero remaining issues):
- Expand config/kb-tags.yaml taxonomy with features, operations,
metrics, limitations sections covering 31 previously-unknown tags
used in field findings (rac, ecpu, refreshable-clone, hnsw, etc.).
- Assign owners for kb/compatibility/, kb/competitive/,
kb/well-architected/ (Diego Cabrera as default until team grows);
kb/pricing/ marked as "Auto-refreshed" since it no longer needs
human ownership.
- kb_linter accepts top-level `date` as fallback for contributor
block; migrate FF-202603-008 from legacy `reported_by` to
contributor block.
- Result: linter goes from 45 issues to 0.
Other:
- Recompute estimation_helpers monthly values in compute.yaml after
the price refresh (they were derived from the old E5/A1 numbers).
- Add kb/README.md — contributor guide (directory map, frontmatter
spec, refresh tooling, review cadence).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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 library 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
- Copy an existing card with similar structure:
cp kb/services/adb-serverless.yaml kb/services/<your-service>.yaml. - Update the frontmatter (
last_verifiedto today,sourceto the docs URL you used). - Fill in fields. Keep gotchas honest — if the service has a limitation, write it down. The KB's value is honesty, not marketing.
- Run
python tools/kb_linter.pyand fix any issues it reports for your file. - Run
make freshnessto 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) |
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
Pricing files
There are exactly two pricing files, both auto-refreshed from the Oracle public pricing API:
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.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.