diegoecab/oci-deal-accelerator
1
1
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
394b821579c0e923cb22b5ae6ad65b4092eac284
oci-deal-accelerator/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

390 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# OCI Deal Accelerator
An AI-powered skill that acts as a **force multiplier for OCI Solutions Architects**. Feed it raw discovery notes from a customer call and get back a complete, defensible architecture proposal — ready to present.
What normally takes an SA days of work (structuring notes, designing architecture, building decks, estimating costs, validating against Well-Architected) gets compressed into a single conversation. The skill doesn't just generate documents — it applies field-tested patterns, real pricing data, and lessons learned from actual OCI engagements to produce artifacts you can confidently put in front of a customer.
**Fully aligned with Oracle's ECAL 3.1 framework** — covers all 9 steps (Ideate → Validate → Plan → Current → Future → Confirm → Adopt → Operate → Improve) with a catalog of 60 artefacts, engagement RACIs for 10 roles, and an ECAL Readiness Scorecard to track engagement completeness.
### Key differentiators
- **ECAL 3.1 native** — engagement RACI, artefact catalog, readiness scoring, and lessons learned per step baked into the workflow
- **Field knowledge, beyond the docs** — built-in KB with real gotchas, workarounds, and sizing lessons from production OCI deployments
- **Honest about trade-offs** — flags OCI limitations and competitive gaps instead of overselling
- **Multi-cloud aware** — supports hybrid/multi-cloud diagrams (AWS, Azure, GCP icons) and considers options like ADB Multicloud before recommending full migration
- **End-to-end coverage** — from discovery notes to go-live checklist, not just the architecture slide
## What It Produces
From unstructured input (meeting notes, emails, Slack threads), the skill generates:
| Artifact | Format | ECAL Phase | ECAL Step |
|---|---|---|---|
| **Customer Profile** — strategic goals, Oracle footprint, industry analysis | YAML | Define | Ideate |
| **Strategy Map** — goals → strategies → capabilities → enablers | YAML | Define | Ideate |
| **Workload Profile** — structured discovery capture | YAML | Define | Ideate |
| **Value Story** — business hypothesis linked to OCI outcomes | YAML | Define | Ideate |
| **Business Case** — TCO, ROI, value drivers, risk assessment | .pptx | Define | Ideate |
| **Joint Engagement Plan** — scope, resources, timeline | YAML | Define | Plan |
| **Discovery Questionnaire** — structured IT landscape collection | YAML | Design | Current |
| **Architecture Diagram** — official Oracle visual style, multi-cloud support | .drawio | Design | Future |
| **Slide Deck** — 6-15 slides scaled to engagement complexity | .pptx | Design | Confirm |
| **Customer PDF** — branded, no internal KB references | .pdf | Design | Confirm |
| **Cost Estimate** — BYOL vs PAYG breakdown with assumptions | YAML | Design | Future |
| **Well-Architected Scorecard** — 5-pillar automated validation | YAML | Design | Future |
| **Operations Model** — day-2 monitoring, patching, incident response | YAML | Design | Future |
| **ECAL Readiness Scorecard** — 60-artefact gap analysis per phase | Text | All | All |
| **Delivery Artifacts** — handover, go-live checklist, success criteria | YAML | Deliver | Adopt |
## Quick Start
Feed `SKILL.md` as a system prompt to any LLM (Claude, GPT-4o, Gemini Pro). Then give it your discovery notes:
```
Here are my notes from the discovery call with Acme Corp:
- 3 Oracle 19c databases on Exadata X8M on-prem, largest is 4TB OLTP
- Using GoldenGate for replication to reporting DB
- Need 99.95% availability, PCI compliance
- Seasonal peaks 3x normal during Black Friday
- Want to reduce costs, current Oracle licensing is $2M/year
- Team has 2 Oracle DBAs, no cloud experience
- CTO wants to move to cloud in 6 months
- Comparing with AWS
```
The skill follows the ECAL workflow automatically: DEFINE (value story) → DESIGN (architecture) → DELIVER (handover).
## Output Formats
```
deck ← default (.pptx)
deck + drawio ← + editable diagram
deck + doc ← + technical document
deck + xlsx ← + cost spreadsheet
deck + pdf ← + customer-facing PDF (branded, no internal refs)
pdf ← customer PDF only
bizcase ← business case deck for customer approval
full ← everything (pptx + drawio + docx + xlsx + pdf)
deliver ← handover + go-live checklist + success criteria
```
## Knowledge Base
The KB is the moat — field experience, not documentation regurgitation.
### Contributing to the KB
Any SA can contribute knowledge to the skill. The KB lives in `kb/` as editable YAML files. Here's where each type of contribution goes:
| What you want to contribute | Where it goes | How |
|---|---|---|
| **Field caveat or workaround** | `kb/field-findings/tracker.yaml` | Menu option 11, or `python tools/findings_cli.py add` |
| **Lesson learned** | `kb/field-knowledge/lessons-learned.yaml` | Edit YAML directly |
| **Undocumented real-world limit** | `kb/field-knowledge/real-world-limits.yaml` | Edit YAML directly |
| **Service caveat** | `kb/field-knowledge/gotchas.yaml` | Edit YAML directly |
| **OCI service info** | `kb/services/<service>.yaml` | Create or edit the service YAML |
| **Architecture pattern** | `kb/patterns/` | Add YAML following existing format |
| **Architecture Center reference** | `kb/architecture-center/catalog.yaml` | `python tools/refresh_arch_catalog.py --url <url>` |
| **Updated pricing** | `kb/pricing/oci-sku-catalog.yaml` (SKUs) or `kb/pricing/compute.yaml` (shapes) | `python tools/refresh_sku_catalog.py --refresh` (SKUs) or `--refresh-domain compute` (shapes). Both auto-pull from the Oracle public pricing API. |
| **Feature compatibility** | `kb/compatibility/adb-feature-matrix.yaml` | Edit the matrix, mark `verified_in_field: true` |
| **Competitive comparison** | `kb/competitive/` | Add or edit YAML with real pros AND cons |
**Fastest path**: if you hit something in an engagement that another SA should know about, use menu option 11 (Report a field finding) — the skill walks you through the format and adds it to the tracker automatically.
### OCI Pricing
All pricing is auto-refreshed from the [Oracle public pricing API](https://apexapps.oracle.com/pls/apex/cetools/api/v1/products/?currencyCode=USD). No manually maintained pricing files.
```
kb/pricing/
├── oci-sku-catalog.yaml # 200+ SKUs across 20 categories — single source of truth
│ Refresh: python tools/refresh_sku_catalog.py --refresh
└── compute.yaml # Shape-level estimation pricing (VMs, BM, GPU)
Refresh: python tools/refresh_sku_catalog.py --refresh-domain compute
kb/field-knowledge/pricing-knowledge.yaml
# Stable pricing context: billing models, BYOL rules,
free tiers, service nuances, hyperscaler comparisons.
Non-numeric — no refresh needed.
```
### DBExpert Database Services Catalog
35 Oracle Database services with full capabilities, multicloud availability (Azure/GCP/AWS locations), SLAs, MAA medals, compliance certifications, and certified Oracle applications. Sourced from the [Oracle DBExpert API](https://oracle-dbexpert.github.io/swagger/).
```
kb/services/dbexpert-catalog.yaml # 35 services, queryable by capability
kb/services/dbexpert-api-reference.yaml # API endpoints and refresh procedure
```
### Architecture Center Catalog
**123 Oracle Architecture Center reference architectures** (`kb/architecture-center/catalog.yaml`) covering Database@Azure/AWS/Google Cloud, networking, security, AI/ML, migration, HA/DR, and more.
During **Phase 2 (DESIGN)**, the skill automatically matches the proposed architecture against the catalog:
- **STRONG MATCH** (≥2 service + ≥1 tag) — cited in the Architecture Decisions slide
- **MODERATE MATCH** (≥1 service + ≥2 tag) — referenced in the technical document
```bash
python tools/refresh_arch_catalog.py --whats-new # crawl What's New pages
python tools/refresh_arch_catalog.py --url <url> # add a single entry
python tools/refresh_arch_catalog.py --validate # validate catalog integrity
```
### Feature Compatibility Matrix
Before recommending a deployment type, the skill checks `kb/compatibility/adb-feature-matrix.yaml` — a field-verified matrix of what works, what doesn't, and what has caveats the docs don't mention.
```bash
python tools/feature_matrix_cli.py check "Auto Scaling" adb_s 23ai
python tools/feature_matrix_cli.py compare adb_s exacs 23ai
python tools/feature_matrix_cli.py gaps dbcs_ee 23ai
```
### Field Findings Tracker
Real issues, limitations, and workarounds encountered during customer engagements.
```bash
python tools/findings_cli.py search "maintenance window"
python tools/findings_cli.py add
python tools/findings_cli.py stats
```
### Competitive Positioning
Honest AWS/Azure/GCP comparisons (`kb/competitive/`) that cover genuine advantages AND genuine gaps. No marketing — only field-verified facts.
## ECAL Readiness Score
Option 12 in the menu scores an engagement against the complete ECAL 3.1 framework:
```
══════════════════════════════════════════
📊 ECAL READINESS SCORECARD
══════════════════════════════════════════
Customer: Acme Corp
Current Phase: DESIGN
Overall Readiness: 62% 🟡
── DEFINE ──────────────────── 85% 🟢
✅ Value Story
✅ Workload Profile
🟡 Customer Profile (missing Oracle footprint)
❌ Strategy Map
✅ Joint Engagement Plan
── DESIGN ──────────────────── 55% 🟠
✅ Future State Architecture
✅ Cost Estimate
🟡 Discovery Questionnaire (partial)
❌ Operational RACI
❌ Recovery Model
...
── TOP 5 GAPS ──
1. ❌ Strategy Map — links solution to business goals
2. ❌ Operational RACI — who runs what post go-live
...
══════════════════════════════════════════
```
The scorecard evaluates each of the **60 ECAL artefacts** from `kb/patterns/ecal-artefacts-catalog.yaml`, weighted by phase (DEFINE 25%, DESIGN 50%, DELIVER 25%). Readiness levels: 🟢 80%+ | 🟡 60-79% | 🟠 40-59% | 🔴 <40%.
After scoring, the skill offers to generate missing artefacts, fix the top gap, or export the scorecard as a slide.
## ECAL 3.1 Coverage
The KB includes comprehensive ECAL 3.1 process knowledge:
| KB File | What it covers |
|---|---|
| `kb/patterns/ecal-artefacts-catalog.yaml` | All 60 ECAL artefacts with description, purpose, and skill support level |
| `kb/patterns/engagement-raci.yaml` | RACI matrices for 10 roles across all 9 ECAL steps + lessons learned |
| `kb/patterns/business-drivers.yaml` | 4-pillar framework (Strategic/Financial/BizOps/ITOps) + hypothesis families |
| `kb/patterns/architecture-principles.yaml` | Design, Deployment, and Service principles from ECAL |
| `kb/patterns/operational-raci.yaml` | 3 operational models (fully managed, co-managed, self-managed) |
| `kb/patterns/service-tiering.yaml` | Platinum/Gold/Silver/Bronze service tier definitions |
| `kb/patterns/environment-catalogue.yaml` | Environment templates per tier (prod, pre-prod, dev, DR) |
| `templates/customer-profile.yaml` | Strategic customer profiling (goals, footprint, industry) |
| `templates/strategy-map.yaml` | Goals → Strategies → Capabilities → Enablers mapping |
| `templates/discovery-questionnaire.yaml` | Structured IT landscape collection with prioritization matrix |
## Business Case Builder
Option 8 in the menu generates a business case deck for customer internal approval:
| Slide | Layout | Content |
|-------|--------|---------|
| Cover | Dark - Title_Pillar | Customer name + subtitle |
| Executive Summary | Impact Statement | Bold 1-sentence opportunity |
| Business Drivers | Multi Statement | 3 key drivers: Why now |
| TCO Comparison | Blank + Table | Current vs OCI (3-5 year) |
| ROI Headline | Blank + Metric | Big number (e.g., "2080% ROI") |
| Value Drivers | Blank + Cards | 4 categories: Cost, Risk, Agility, Innovation |
| Risk Assessment | Blank + 2-Column | Migration risks vs Do-nothing risks |
| Roadmap | Blank + Timeline | Implementation phases |
| Recommendation | Dark Impact | Clear ask with next steps |
Uses the **Oracle FY26 official PowerPoint template** with Redwood design system.
```bash
python tools/oci_bizcase_gen.py --spec business-case.yaml --output business-case.pptx
```
## Welcome Flow
When you start a conversation without discovery notes, the skill presents an interactive menu:
```
🏗️ OCI Deal Accelerator
━━━━━━━━━━━━━━━━━━━━━━━
Compresses your SA cycle from discovery to proposal — days to hours.
Aligned with Oracle's ECAL framework (Define → Design → Deliver).
What do you want to do?
DESIGN & PROPOSE
─────────────────
1. 📋 Full proposal — notes → architecture + deck + diagram + costs
2. 📐 Architecture diagram — YAML or description → .drawio
3. 📊 Slide deck — architecture → .pptx
4. 💰 Cost estimate — services + sizing → PAYG vs BYOL
VALIDATE & CHECK
─────────────────
5. ✅ Well-Architected review — 5-pillar scoring + gaps
6. 🔍 Feature compatibility — "does ADB-S support X?"
7. 🆚 Competitive comparison — honest pros & cons vs AWS/Azure/GCP
STRATEGY & BUSINESS
─────────────────
8. 💼 Business case — TCO, ROI, value drivers → exec deck
KNOWLEDGE BASE
─────────────────
9. 🔎 Field findings — real issues + workarounds
10. 📚 Reference architecture — Architecture Center lookup
11. ➕ Report finding — log a gotcha from your engagement
ECAL GOVERNANCE
─────────────────
12. 📊 ECAL readiness score — 60-artefact gap analysis
━━━━━━━━━━━━━━━━━━━━━━━
Pick a number, or just describe what you need.
```
If you paste discovery notes directly, the skill skips the menu and goes straight to the full proposal flow.
## Tools
```bash
# Slide deck generation (technical proposal)
python tools/oci_deck_gen.py --spec examples/proposal-spec.yaml --output proposal.pptx
# Customer-facing PDF (branded, no internal KB refs)
python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf
python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf --diagram arch.png
# Business case deck
python tools/oci_bizcase_gen.py --spec business-case.yaml --output business-case.pptx
# Architecture diagram
python tools/oci_diagram_gen.py --spec examples/diagram-spec.yaml --output arch.drawio
# Output orchestrator (multiple formats at once)
python tools/oci_output.py --spec examples/proposal-spec.yaml --format full --output-dir output/
# Architecture Center catalog
python tools/refresh_arch_catalog.py --validate
python tools/refresh_arch_catalog.py --whats-new
# Feature compatibility
python tools/feature_matrix_cli.py check "Auto Scaling" adb_s 23ai
python tools/feature_matrix_cli.py compare adb_s exacs 23ai
# Field findings
python tools/findings_cli.py search "maintenance window"
python tools/findings_cli.py stats
# KB governance
python tools/kb_cli.py health
# WA validation
python scripts/validate-architecture.py \
--profile examples/sample-workload-profile.yaml \
--architecture examples/sample-architecture.yaml \
--output scorecard.yaml
# Build automation
make help
```
## Multi-LLM Support
The skill is LLM-agnostic. The same KB and templates work across platforms:
| Platform | How to use |
|----------|-----------|
| **Claude Code** | Uses `SKILL.md` + `CLAUDE.md` natively |
| **OpenAI Codex** | Uses `AGENTS.md` + `.agents/skills/` (see below) |
| **ChatGPT / GPT-4o** | Paste SKILL.md as system prompt |
| **Gemini Pro** | Paste SKILL.md as system instruction |
### OpenAI Codex Setup
The repo is 100% compatible with [Codex CLI](https://github.com/openai/codex). Codex auto-discovers the skill on startup:
```
├── AGENTS.md # Project instructions (Codex reads automatically)
├── .agents/skills/oci-deal-accelerator/
│ └── SKILL.md # Full skill definition (YAML frontmatter + instructions)
└── codex/
└── README.md # Detailed setup guide
```
```bash
# Just run Codex from the project root — auto-discovers everything
cd oci-deal-accelerator
codex
# Or load the skill explicitly
codex --skill oci-deal-accelerator
```
For temporary overrides (e.g., focusing on a specific customer), create `AGENTS.override.md` at the project root — it takes highest priority.
Full setup details: [`codex/README.md`](codex/README.md)
## Roadmap
### ECAL Completeness (see `docs/ecal-gaps-backlog.md` for full list)
- Integration Catalog template — detailed integration mapping with data flows
- Cloud Operating Framework — 52-week operational plan (9 capability areas)
- OCI Operationalization Framework — 5-milestone deployment methodology
- POD (Pool of Databases) pattern — large-scale DB consolidation
- Banking/Financial compliance pattern — EBA/FCA/PRA mapped to OCI services
- ExaCC managed service pattern — complete ExaCC + ZDLRA/ZFS/OEM/OKV
### Platform
- Interactive what-if cost simulator (adjust ECPU/storage/commitment live)
- Automated migration complexity scoring from discovery notes
- Multi-region DR cost optimizer
- Engagement timeline generator (Gantt-style from Joint Engagement Plan)
- DBExpert API auto-refresh for database service catalog
- KB vectorizada en base de datos (RAG) — almacenar knowledge base en OCI 23ai con embeddings para busqueda semantica en lugar de lookup estatico por YAML
## Requirements
- Python 3.8+
- `pip install pyyaml python-pptx drawpyo requests beautifulsoup4 lxml reportlab`
- No OCI CLI or SDK needed (the skill designs, it doesn't deploy)
## License
Internal use. Not for distribution.
Reference in New Issue View Git Blame Copy Permalink