forked from diegoecab/oci-deal-accelerator

Files

root ca93a0aa4e Auto-refresh KB pricing, align skill with Anthropic best practices

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>

2026-04-08 23:59:32 -03:00

6.1 KiB

Raw Blame History

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_verified to today, source to 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.py and fix any issues it reports for your file.
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)
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.

6.1 KiB Raw Blame History