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>
317 lines
12 KiB
YAML
317 lines
12 KiB
YAML
# =============================================================================
|
|
# FIELD FINDINGS TRACKER
|
|
# =============================================================================
|
|
#
|
|
# INTERNAL & CONFIDENTIAL — DO NOT SHARE EXTERNALLY
|
|
#
|
|
# Log of real issues, limitations, bugs, and surprises found during customer
|
|
# engagements. Each entry is a finding that another architect should know about
|
|
# before hitting the same wall.
|
|
#
|
|
# Entry format:
|
|
# id: Unique identifier (FF-YYYYMM-NNN)
|
|
# date: When discovered (YYYY-MM-DD)
|
|
# contributor: Attribution block (replaces flat "reported_by")
|
|
# name: Who found it (required)
|
|
# team: Team or role (required)
|
|
# client: Client name or anonymized reference (optional)
|
|
# context: Brief context — PoC, migration, assessment (optional)
|
|
# confidence: validated / observed / reported / inferred (required)
|
|
# product: OCI product/service affected
|
|
# version: Product version if relevant
|
|
# severity: CRITICAL / HIGH / MEDIUM / LOW / INFO
|
|
# category: bug / limitation / undocumented / gotcha / workaround / performance
|
|
# summary: One-line description
|
|
# detail: Full description of the finding
|
|
# workaround: How to work around it (if known)
|
|
# oracle_sr: Oracle SR number (if filed)
|
|
# status: open / resolved / wontfix / acknowledged / monitoring
|
|
# resolved_date: When resolved (if applicable)
|
|
# resolution: How it was resolved
|
|
# affects_matrix: Feature matrix entry this relates to (if any)
|
|
# tags: Searchable tags
|
|
# confirmations: List of peer confirmations (optional)
|
|
#
|
|
# HOW TO ADD:
|
|
# 1. Add entry at the TOP of the findings list (newest first)
|
|
# 2. Use next sequential ID: FF-YYYYMM-NNN
|
|
# 3. Be specific — include CLI versions, API errors, exact messages
|
|
# 4. If you filed an SR, include the number
|
|
# 5. Update status when resolved
|
|
# =============================================================================
|
|
|
|
---
|
|
last_updated: "2026-03-14"
|
|
|
|
findings:
|
|
|
|
- id: "FF-202603-008"
|
|
date: "2026-03-14"
|
|
contributor:
|
|
name: "Diego Cabrera"
|
|
team: "Field Architecture"
|
|
client: "Vector Search Customer"
|
|
context: "AI Vector Search engagement"
|
|
confidence: "validated"
|
|
product: "ADB-S"
|
|
version: "23ai"
|
|
severity: "HIGH"
|
|
category: "limitation"
|
|
summary: "Distributed HNSW indexes not available — 100M+ vector search requires partitioning workaround"
|
|
detail: |
|
|
ADB-S AI Vector Search supports HNSW indexes but they are node-local on
|
|
multi-node RAC (≥64 ECPUs). At 100M+ vectors, queries on a 2-node RAC
|
|
miss vectors on the other node. Results are either incomplete or require
|
|
cross-node scan that blows P95 >200ms.
|
|
|
|
Workaround from internal DB PM team: hash-partition vector table on
|
|
vector_id, create partition-local HNSW index. Queries hit single
|
|
partition on single node, maintaining <50ms at 100M scale.
|
|
|
|
Requires table redesign — cannot be applied to existing unpartitioned
|
|
vector tables without data reload.
|
|
workaround: |
|
|
Hash-partition vector table by vector_id. Create HNSW index as LOCAL
|
|
(partition-level). Ensure partition pruning in queries.
|
|
Source: internal DB PM team contact [name].
|
|
Validated on ADB-S 23ai with 120M vectors, P95 = 38ms on 64 ECPU.
|
|
oracle_sr: ""
|
|
status: "acknowledged"
|
|
resolved_date: null
|
|
resolution: null
|
|
affects_matrix: "AI Vector Search (HNSW)"
|
|
tags: ["vector-search", "hnsw", "distributed", "rac", "partitioning", "100m", "latency", "ai-vector-search"]
|
|
|
|
- id: "FF-202603-001"
|
|
date: "2026-03-10"
|
|
contributor:
|
|
name: "Diego Cabrera"
|
|
team: "Field Architecture"
|
|
client: "Strategic Migration Customer"
|
|
context: "Production migration"
|
|
confidence: "validated"
|
|
product: "OCI CLI"
|
|
version: "CLI 3.73.1 and 3.75.0"
|
|
severity: "MEDIUM"
|
|
category: "bug"
|
|
summary: "OCI CLI --autonomous-database-maintenance-window has JSON serialization bug"
|
|
detail: |
|
|
The --autonomous-database-maintenance-window parameter fails with a JSON
|
|
serialization error on both OCI CLI 3.73.1 (Cloud Shell) and 3.75.0
|
|
(VM decabrer-4S46W64). The expected JSON schema is:
|
|
{"dayOfWeek": {"name": "SATURDAY"}, "hourOfDay": 4}
|
|
But the CLI cannot serialize this properly. API returns 403 at create time.
|
|
Tested via dry-run: the 204 response is received but actual creation fails.
|
|
workaround: "Use OCI Console to set maintenance window. Or set post-creation via API directly (not CLI)."
|
|
oracle_sr: ""
|
|
status: "open"
|
|
resolved_date: null
|
|
resolution: null
|
|
affects_matrix: "OCI CLI Management"
|
|
tags: ["cli", "maintenance-window", "adb", "dep", "json", "serialization"]
|
|
|
|
- id: "FF-202603-002"
|
|
date: "2026-03-08"
|
|
contributor:
|
|
name: "Diego Cabrera"
|
|
team: "Field Architecture"
|
|
client: "Strategic Migration Customer"
|
|
context: "Production migration"
|
|
confidence: "validated"
|
|
product: "ADB-S Dedicated Elastic Pool (DEP)"
|
|
version: "23ai"
|
|
severity: "HIGH"
|
|
category: "limitation"
|
|
summary: "ADG must be disabled before joining Dedicated Elastic Pool"
|
|
detail: |
|
|
When attempting to add an ADB-S instance with active Autonomous Data Guard
|
|
to a Dedicated Elastic Pool, the operation fails. ADG must be explicitly
|
|
disabled before the instance can join the DEP. This is a known issue
|
|
acknowledged by Oracle but not prominently documented.
|
|
|
|
Impact: requires a brief HA gap during DEP onboarding. Must coordinate
|
|
with the customer's change window.
|
|
workaround: "Disable ADG → join DEP → re-enable ADG. Plan for ~15 min HA gap."
|
|
oracle_sr: ""
|
|
status: "acknowledged"
|
|
resolved_date: null
|
|
resolution: null
|
|
affects_matrix: "Elastic Pool Membership"
|
|
tags: ["dep", "adg", "elastic-pool", "ha", "limitation"]
|
|
|
|
- id: "FF-202603-003"
|
|
date: "2026-03-05"
|
|
contributor:
|
|
name: "Diego Cabrera"
|
|
team: "Field Architecture"
|
|
client: "Strategic Migration Customer"
|
|
context: "Production migration"
|
|
confidence: "validated"
|
|
product: "ADB-S Dedicated Elastic Pool (DEP)"
|
|
version: "23ai"
|
|
severity: "MEDIUM"
|
|
category: "undocumented"
|
|
summary: "DEP maintenance window immutable post-creation — change only via SR"
|
|
detail: |
|
|
The maintenance window for a Dedicated Elastic Pool cannot be changed
|
|
after creation via Console, CLI, or API. The only way to change it is
|
|
by filing a Service Request with Oracle Support.
|
|
|
|
Default window is Saturday/Sunday. Other days require specifying at
|
|
creation time (which itself has the CLI bug — see FF-202603-001) or
|
|
requesting via SR.
|
|
workaround: "Set desired window at DEP creation time (via Console, not CLI). If missed, file SR."
|
|
oracle_sr: ""
|
|
status: "acknowledged"
|
|
resolved_date: null
|
|
resolution: null
|
|
affects_matrix: "Auto Patching"
|
|
tags: ["dep", "maintenance-window", "immutable", "sr-required"]
|
|
|
|
- id: "FF-202603-004"
|
|
date: "2026-03-01"
|
|
contributor:
|
|
name: "Diego Cabrera"
|
|
team: "Field Architecture"
|
|
client: "Strategic Migration Customer"
|
|
context: "Production migration"
|
|
confidence: "validated"
|
|
product: "ADB-S"
|
|
version: "23ai"
|
|
severity: "MEDIUM"
|
|
category: "gotcha"
|
|
summary: "DEP provisioning takes days to weeks depending on capacity"
|
|
detail: |
|
|
Dedicated Elastic Pool provisioning is NOT instant like ADB-S Serverless.
|
|
It requires physical Exadata infrastructure allocation. Lead time varies
|
|
from 3 days (if capacity available in region) to 2-3 weeks (if capacity
|
|
needs to be provisioned).
|
|
|
|
Billing starts only at AVAILABLE state, not at request time.
|
|
Co-location of existing ADB-S instances happens at the next maintenance
|
|
window after joining, not immediately.
|
|
workaround: "Request DEP early in the project timeline. Don't make it a critical-path dependency in week 1."
|
|
oracle_sr: ""
|
|
status: "acknowledged"
|
|
resolved_date: null
|
|
resolution: null
|
|
affects_matrix: "Elastic Pool Membership"
|
|
tags: ["dep", "provisioning", "lead-time", "capacity", "planning"]
|
|
|
|
- id: "FF-202603-005"
|
|
date: "2026-02-20"
|
|
contributor:
|
|
name: "Diego Cabrera"
|
|
team: "Field Architecture"
|
|
client: "Strategic Migration Customer"
|
|
context: "Production migration"
|
|
confidence: "observed"
|
|
product: "ADB-S"
|
|
version: "23ai"
|
|
severity: "LOW"
|
|
category: "gotcha"
|
|
summary: "Refreshable Clone failed refresh leaves clone in AVAILABLE state — detection delay"
|
|
detail: |
|
|
When a Refreshable Clone's auto-refresh fails, the clone remains in
|
|
AVAILABLE state (not DISCONNECTED). The Elastic Pool leader monitors
|
|
lifecycle state changes, not refresh success/failure.
|
|
|
|
This means a failed refresh is NOT immediately detected by the
|
|
infrastructure. The stale data window equals the ADG RTO for
|
|
unplanned scenarios.
|
|
workaround: |
|
|
Planned switchovers: DBMS_PROXY_SQL.DISABLE_READ_ONLY_OFFLOAD proactively.
|
|
Unplanned: OCI Events + OCI Function that monitors refresh state and
|
|
disables read offload automatically. Reduces stale window to ~ADG RTO.
|
|
oracle_sr: ""
|
|
status: "monitoring"
|
|
resolved_date: null
|
|
resolution: null
|
|
affects_matrix: "Refreshable Clone"
|
|
tags: ["refreshable-clone", "stale-reads", "elastic-pool", "detection-delay", "proxysql"]
|
|
|
|
- id: "FF-202603-006"
|
|
date: "2026-02-15"
|
|
contributor:
|
|
name: "Diego Cabrera"
|
|
team: "Field Architecture"
|
|
client: "Strategic Migration Customer"
|
|
context: "Migration assessment"
|
|
confidence: "validated"
|
|
product: "OCI DMS"
|
|
version: "current"
|
|
severity: "MEDIUM"
|
|
category: "limitation"
|
|
summary: "Bidirectional GoldenGate replication not yet available in DMS"
|
|
detail: |
|
|
OCI Database Migration Service does not support bidirectional GoldenGate
|
|
replication. This is needed for zero-hard-cutover migration workflows
|
|
where the customer wants to run both source and target in parallel with
|
|
data flowing both ways during transition.
|
|
|
|
Feature request submitted to Oracle DMS PM team. In their pipeline but
|
|
no committed timeline. Offered beta participation.
|
|
workaround: "Use standalone GoldenGate deployment (not DMS-managed) for bidirectional replication."
|
|
oracle_sr: ""
|
|
status: "open"
|
|
resolved_date: null
|
|
resolution: null
|
|
affects_matrix: null
|
|
tags: ["dms", "goldengate", "bidirectional", "migration", "zero-downtime"]
|
|
|
|
- id: "FF-202603-007"
|
|
date: "2026-02-10"
|
|
contributor:
|
|
name: "Diego Cabrera"
|
|
team: "Field Architecture"
|
|
client: "Pepe SRL"
|
|
context: "Discovery engagement"
|
|
confidence: "validated"
|
|
product: "ADB-S"
|
|
version: "23ai"
|
|
severity: "INFO"
|
|
category: "gotcha"
|
|
summary: "ADB-S Serverless RAC node split threshold at 64 ECPUs"
|
|
detail: |
|
|
ADB-S Serverless runs on 1 RAC node at ≤24 ECPUs and splits to 2 nodes
|
|
at 64 ECPUs (16 cpu_count each). The gv$instance view only shows nodes
|
|
where the PDB is open.
|
|
|
|
This affects connection pooling behavior and session distribution.
|
|
Applications should use UCP or JDBC connection pool with FAN events
|
|
to handle the multi-node scenario properly.
|
|
workaround: "Ensure connection pool configuration handles multi-node. Use UCP with FAN."
|
|
oracle_sr: ""
|
|
status: "acknowledged"
|
|
resolved_date: null
|
|
resolution: null
|
|
affects_matrix: null
|
|
tags: ["adb-s", "rac", "ecpu", "node-split", "connection-pooling"]
|
|
|
|
# =========================================================================
|
|
# TEMPLATE — Copy this for new entries:
|
|
# =========================================================================
|
|
# - id: "FF-YYYYMM-NNN"
|
|
# date: "YYYY-MM-DD"
|
|
# contributor:
|
|
# name: ""
|
|
# team: ""
|
|
# client: "" # Optional — anonymize if sensitive
|
|
# context: "" # Optional — PoC, migration, assessment
|
|
# confidence: "" # validated / observed / reported / inferred
|
|
# product: ""
|
|
# version: ""
|
|
# severity: "" # CRITICAL / HIGH / MEDIUM / LOW / INFO
|
|
# category: "" # bug / limitation / undocumented / gotcha / workaround / performance
|
|
# summary: ""
|
|
# detail: |
|
|
#
|
|
# workaround: ""
|
|
# oracle_sr: ""
|
|
# status: "" # open / resolved / wontfix / acknowledged / monitoring
|
|
# resolved_date: null
|
|
# resolution: null
|
|
# affects_matrix: null # Feature matrix entry name, or null
|
|
# tags: []
|
|
# confirmations: [] # Peer confirmations
|