raulrgmx/oci-deal-accelerator
1
0
Fork 0
forked from diegoecab/oci-deal-accelerator
Code Pull Requests Activity
Files
886c09ad1059693cba06f6683c04086c22710759
oci-deal-accelerator/kb/README.md
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

123 lines
6.1 KiB
Markdown
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:
```yaml
---
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) |
| 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:
```bash
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](https://apexapps.oracle.com/pls/apex/cetools/api/v1/products/?currencyCode=USD):
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
```bash
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.
View Git Blame Copy Permalink