SKILL.md option 2: explicit format question + numbered procedure steps

A Codex session showed the gap: option 2's prose asked the user to describe the architecture but only mentioned the output formats in passing ("if you want X / if you want Y"), so the agent never asked which format(s). Codex also skipped the reference-architecture lookup and went straight to grepping ``examples/`` for pre-existing specs — ``examples/`` is previous user output, not the authoritative Oracle catalog. Two persistent fixes for any agent (Claude Code, Codex, Cursor, …): 1. Option 2 now asks two explicit questions in one message and waits for both answers before doing anything: (1) describe / paste spec, (2) pick output format(s) — drawio, native PPTX, or both. 2. The procedure is restated as a numbered list directly under option 2 (no longer a single-sentence reference to docs/skill/output-formats.md). Step 1 explicitly says use ``archcenter_pattern_lookup.py`` against the catalog and explicitly forbids using ``examples/`` as a reference source. Synced to the Codex copy at .agents/skills/oci-deal-accelerator/SKILL.md via ``make sync-skill`` so both agents see the same instructions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-25 22:49:47 -03:00
parent a0a059887a
commit a1ad3a6fa1
2 changed files with 175 additions and 35 deletions
--- a/.agents/skills/oci-deal-accelerator/SKILL.md
+++ b/.agents/skills/oci-deal-accelerator/SKILL.md
@@ -17,32 +17,54 @@ You follow the **Oracle ECAL framework** (Define → Design → Deliver) to prod

 When the user starts a conversation without providing discovery notes or a specific request, present the welcome message and capability menu.

-### Pre-flight: KB freshness check
+### Pre-flight checks

-**Before showing the welcome message**, run `make kb-check 2>/dev/null` and parse the JSON output. Behavior based on the result:
+Run these checks silently **before** showing the welcome message. **CRITICAL:** Never show command execution, tool output, or errors to the user. If any check fails, silently skip it and proceed to the welcome message. These checks are informational — they NEVER block the user.

- **`stale_count == 0`** → proceed directly to the welcome message. No banner.
- **`stale_count > 0` and at least one file has `refreshable: true`** → prepend this banner above the menu and ask the user inline:
+#### Check 1: KB changelog banner
+
+Read the file `kb/CHANGELOG.md` and extract the **most recent date and first bullet point**. If the file exists and has entries, prepend a one-line banner above the welcome message:
+
+```
+📢 KB updated (<date>): <first bullet summary>
+```
+
+Example: `📢 KB updated (Apr 14): Diagram generator calibrated from 37 Oracle ref architectures`
+
+If the file is missing or empty, skip — no banner.
+
+#### Check 2: Local repo updates (git users only)
+
+Run `git fetch --dry-run origin main 2>/dev/null`. If the output contains any text (meaning there are remote commits not yet pulled), prepend this banner:
+
+```
+📢 KB updates available — run `git pull` to get latest prices and fixes.
+```
+
+If the command fails (not a git repo, no network, MCP deployment), silently skip. This check is only relevant for users running the skill from a local git clone.
+
+#### Check 3: KB freshness
+
+Run `make kb-check 2>/dev/null` and parse the JSON output. Behavior:
+
+- **`stale_count == 0`** → no banner.
+- **`stale_count > 0` and at least one file has `refreshable: true`** → prepend banner and ask inline:

  ```
  ⚠️  KB freshness: <N> file(s) outdated (oldest: <file> — <age_days>d).
-      <M> can be auto-refreshed (SKU catalog, Architecture Center).
-      Refresh now before showing the menu? [y/N]
+      <M> can be auto-refreshed. Refresh now? [y/N]
  ```

-  - If the user replies `y` / `yes` / `sí` → run `make freshness-refresh`, wait for completion, then show the menu.
-  - If the user replies `n` / anything else → show the menu immediately, with a one-line compact reminder above it: `⚠️ <N> KB file(s) stale — run /freshness or make freshness-refresh later.`
+  - `y` / `yes` / `sí` → run `make freshness-refresh`, then show menu.
+  - Anything else → show menu with one-line reminder: `⚠️ <N> KB file(s) stale — run make freshness-refresh later.`

- **`stale_count > 0` but no file has `refreshable: true`** (only manual files stale) → prepend a non-blocking informational banner above the menu, do NOT ask:
+- **`stale_count > 0` but no `refreshable: true`** → non-blocking info banner, then show menu directly:

  ```
  ⚠️  KB freshness: <N> file(s) need manual review (oldest: <file> — <age_days>d).
-      No automated refresh available — see kb/README.md for review process.
  ```

-  Then show the menu directly.
-
-**Important**: this check is informational, not gating. If `kb_freshness.py` errors out (exit 2 or missing tool), silently fall back to showing the welcome message — never block the user on tooling failures.
+If `make kb-check` errors out (exit ≠ 0, missing make, missing Python, missing tool), **silently skip** — no error output, no banner, no mention of failure.

 ### Welcome Message

@@ -63,9 +85,9 @@ Present these options as a compact numbered list. Each option has a bold title f
 ```
 DESIGN & PROPOSE
 ─────────────────
- 1. 📋 Full proposal — *notes → architecture + deck + diagram + costs*
- 2. 📐 Architecture diagram — *YAML or description → .drawio*
- 3. 📊 Slide deck — *architecture → .pptx*
+ 1. 📋 Full proposal — *notes → architecture + deck + native PPTX diagram + costs*
+ 2. 📐 Architecture diagram — *description → .drawio or native PPTX*
+ 3. 📊 Slide deck — *architecture → .pptx with native OCI diagram*
 4. 💰 Cost estimate — *services + sizing → PAYG vs BYOL*

 VALIDATE & CHECK
@@ -100,8 +122,26 @@ Pick a number, or just describe what you need.
 ### Behavior Rules

 - If the user picks **1**, ask: "Paste your discovery notes (meeting notes, emails, whatever you have)."
- If the user picks **2**, ask: "Describe the architecture you want to diagram, or paste a YAML spec if you have one."
- If the user picks **3**, ask: "Describe the architecture or paste the spec. I'll generate the deck."
+- If the user picks **2**, ask **two explicit questions** in one message and wait for both answers before doing anything else:
+
+  ```
+  1. Describe the architecture you want to diagram (or paste a YAML spec if you have one).
+  2. Which output format(s) do you want? Pick one or more:
+       (a) .drawio — editable technical diagram
+       (b) .pptx — native Oracle-style PowerPoint diagram/slide
+       (c) both
+  ```
+
+  After the user answers, **follow these steps in order — do NOT skip step 1**:
+  1. **Reference-architecture lookup.** Run `python tools/archcenter_pattern_lookup.py "<topology keywords>"` against `kb/architecture-center/catalog.yaml` (123 Oracle-curated entries with cached `.drawio` / `_description.md` under `kb/diagram/assets/archcenter-refs/`). Pick the highest-scoring entry whose topology matches; copy its container nesting, padding, and AD/subnet placement. **Do NOT search `examples/` for references** — `examples/` are previous user outputs, not authoritative Oracle conventions.
+  2. **Pre-generation review.** Confirm the component list with the user (REQUESTED + TECHNICAL DEPENDENCIES per the whitelist).
+  3. **Author the `absolute_layout` spec** following the geometry rules.
+  4. **Spec validator runs automatically** before either renderer (`tools/diagram_spec_validator.py`). Fix any errors.
+  5. **Render.** `oci_diagram_gen.py` for drawio, `oci_deck_gen.py` for PPTX.
+  6. **Visually verify.** `tools/oci_pptx_render.py` to rasterize, then read the PNG.
+
+  Full reference: `docs/skill/output-formats.md` § "Standard diagram-generation procedure (MANDATORY)".
+- If the user picks **3**, ask: "Describe the architecture or paste the spec. I'll generate the deck with a native OCI PowerPoint diagram when the architecture is structured enough."
 - If the user picks **4**, ask: "What services and sizing? (e.g., 'ADB-S 8 OCPU + 2 VMs + FastConnect')"
 - If the user picks **5**, ask: "Describe your architecture or paste the spec. I'll run the 5-pillar review." Then follow the WA review flow:
  1. Parse input to build a workload profile YAML (flags) and architecture YAML
@@ -126,7 +166,7 @@ Pick a number, or just describe what you need.
  6. Assess migration risks from `kb/field-knowledge/gotchas.yaml` and do-nothing risks
  7. Compare with alternatives using `kb/competitive/*`
  8. Generate implementation roadmap based on engagement tier
-  9. Produce a 8-10 slide deck using Oracle FY26 template (`config/oracle-pptx-layouts.yaml` → `business_case` type)
+  9. Produce a 8-10 slide deck using Oracle FY26 template (`config/oracle-pptx-layouts.yaml` → `business_case` type), using a native OCI PowerPoint diagram when the architecture is structured enough
  10. Output: business-case.pptx + business-case.yaml (reusable spec)
 - If the user picks **9**, ask: "What topic? (e.g., 'DEP', 'TAC', 'maintenance window', 'vector search')"
 - If the user picks **10**, ask: "What kind of architecture? (e.g., 'ADB + APEX', 'cross-region DR', 'data lakehouse')"
@@ -254,6 +294,32 @@ Full tier definitions and artifact matrix: [docs/engagement-tiers.md](docs/engag

 **Step 1 — Ideate:** Parse discovery notes into a **Workload Profile** (`templates/workload-profile.yaml`). Formulate a value hypothesis: "If we [technical action], the customer achieves [business outcome]." Use `kb/patterns/business-patterns.yaml` for proven business-level patterns.

+**Step 1b — Extraction Receipt (MANDATORY).** After parsing discovery notes, present an extraction receipt to the user BEFORE proceeding. This ensures the architecture is built on confirmed facts, not assumptions:
+  ```
+  📋 Extraction Receipt
+  ━━━━━━━━━━━━━━━━━━━━
+
+  From your input I extracted:
+
+  CONFIRMED (explicitly stated):
+  • [field]: [value] — source: "[exact quote or reference from notes]"
+  • [field]: [value] — source: "[exact quote or reference from notes]"
+
+  INFERRED (not stated, derived from context):
+  • [field]: [value] — reason: "[why I inferred this]"
+
+  MISSING (needed but not provided):
+  • [field] — needed for: [which artifact or decision needs it]
+
+  ━━━━━━━━━━━━━━━━━━━━
+  Confirm, correct, or fill gaps before I proceed.
+  ```
+  Rules:
+  - Every field in the workload profile that you populate must appear in either CONFIRMED or INFERRED.
+  - Do NOT proceed to Step 2 until the user confirms the receipt.
+  - If the user provides additional data, update the receipt and re-confirm.
+  - When generating the workload-profile.yaml, tag each field with `source: customer` (confirmed), `source: inferred`, or `source: default` so the SA knows what to validate with the customer.
+
 **Step 2 — Validate:** Test the hypothesis for SMART criteria (Specific, Measurable, Attainable, Relevant, Time-based). Identify gaps. Check technical feasibility against `kb/services/` and `kb/compatibility/`.

 **Step 3 — Service Tiering:** After parsing databases, assign each workload a tier (Platinum/Gold/Silver/Bronze) based on SLA requirements, compliance needs, and business criticality. Use the auto-assignment rules in `kb/patterns/service-tiering.yaml`. Present the assignment and ask the architect to confirm or adjust.
@@ -287,7 +353,7 @@ Capture enough about current state to architect the future. Frame the problem

 1. **Select services** from `kb/services/` across the full OCI catalog
 2. **Dimension each service** using `kb/sizing/` rules. For Oracle DBs, use AWR metrics if available. Apply conversion ratios. For ADB-S, size base OCPUs for P75.
-3. **Compose topology** from `kb/patterns/` blocks. Check conflicts, add implied dependencies, apply compliance overlays. Use `kb/patterns/application-patterns.yaml` for workload-type guidance.
+3. **Compose topology** from `kb/patterns/` blocks. Check conflicts and apply compliance overlays. Use `kb/patterns/application-patterns.yaml` for workload-type guidance. **Do NOT silently add components** — only add technical dependencies from the closed whitelist in the Guardrails section below. Everything else must be proposed as optional in the pre-generation review.
 4. **Architecture Principles** — Select applicable principles from `kb/patterns/architecture-principles.yaml` based on the workload profile. Check `applies_when` conditions. Include in the deck as a governance slide.
 5. **Environment Catalogue** — Expand each workload into environments (Prod/Pre-Prod/Dev-Test/DR) using the tier templates in `kb/patterns/environment-catalogue.yaml`. Apply cost optimization rules. Include in the deck and in the cost estimate.
 6. **Design deployment** — environment strategy, IaC approach, CI/CD pipeline
@@ -310,6 +376,28 @@ Capture enough about current state to architect the future. Frame the problem

 #### Confirm (Solution Proposal)

+**Completeness gate (MANDATORY before generating artifacts).** Before calling any generation tool (deck, diagram, BOM, PDF), verify that critical fields are populated based on engagement tier:
+
+| Field | Small | Standard | Complex |
+|---|---|---|---|
+| customer_name | required | required | required |
+| workload_type | required | required | required |
+| databases (type + count) | required | required | required |
+| primary_region | required | required | required |
+| compliance_frameworks | — | required | required |
+| RTO / RPO | — | required | required |
+| team_size | — | required | required |
+| current_infrastructure | — | required | required |
+| migration_driver | — | required | required |
+| environment_strategy | — | — | required |
+| operational_model | — | — | required |
+| multi_region_topology | — | — | required |
+| data_residency | — | — | required |
+
+- If **required** fields are missing: ask the user before generating.
+- If **optional** fields are missing: list them as assumptions in the output (e.g., "Assumed: PAYG pricing, single environment, no compliance requirements").
+- Fields tagged `source: inferred` in the workload profile count as populated but should be flagged as assumptions.
+
 Assemble all design work into a proposal. Ensure all propositions are **SMART**. Quality matters — it must look professional.

 **Outputs by tier:** See artifact matrix in [docs/engagement-tiers.md](docs/engagement-tiers.md)
@@ -364,6 +452,14 @@ See [docs/skill/output-formats.md](docs/skill/output-formats.md) for the per-cus

 ---

+## Cookbook: Building Tool Payloads
+
+Before mapping customer requirements to SKUs for `generate_bom`, `generate_bom_appca`, or `generate_cost_estimate`, check [docs/bom-cookbook.md](docs/bom-cookbook.md) — it has copy-paste recipes for common patterns (ExaCS X11M BYOL, ADB-Dedicated, ADB-S + Block + FastConnect) and explicitly names the gotchas that otherwise burn exploration turns (e.g. ADB-Dedicated shares infrastructure SKUs with ExaCS — there are no separate `adb_dedicated` SKUs in the catalog).
+
+If a requirement does not match a recipe, `grep` [`kb/pricing/oci-sku-catalog.yaml`](kb/pricing/oci-sku-catalog.yaml) and consult `kb/services/` before inventing SKUs.
+
+---
+
 ## Knowledge Base

 KB lives under `kb/`. See [kb/README.md](kb/README.md) for the directory map, frontmatter requirements, refresh tooling, and contributor guide.
@@ -418,23 +514,49 @@ KB lives under `kb/`. See [kb/README.md](kb/README.md) for the directory map, fr

 ## Guardrails

- **Only what the user asked for.** Never add services, components, or features the user did not request — this includes observability (Monitoring, Logging, Events), security services (Data Safe, Vault, Cloud Guard, WAF), sizing details, connection types (RPC, peering), and any "nice to have" additions. Adding unrequested components wastes the architect's time and erodes trust.
+- **Only what the user asked for.** Never add services, components, or features the user did not request — this includes observability (Monitoring, Logging, Events), security services (Data Safe, Vault, Cloud Guard, WAF), sizing details, connection types (RPC, peering), and any "nice to have" additions. Adding unrequested components wastes the architect's time and erodes trust. The ONLY exception is the closed whitelist of technical dependencies below.
+
+- **Technical dependency whitelist (closed — nothing else is auto-added):**
+
+  | If the user requests… | Auto-include | Reason |
+  |---|---|---|
+  | FastConnect | DRG | FastConnect terminates on DRG — cannot work without it |
+  | VPN Connect | DRG | IPSec tunnels terminate on DRG |
+  | ADB-S / ExaCS with backup to Object Storage | Service Gateway | Backup traffic requires SGW for Oracle Services Network |
+  | Any service in a public subnet | Internet Gateway | Public subnet routing requires IGW |
+  | Any private subnet service needing internet egress | NAT Gateway | Private-to-internet routing requires NAT |
+  | Cross-region DR (Data Guard, FSDR) | Remote Peering Connection (RPC) | Cross-region VCN connectivity requires RPC on both DRGs |
+
+  Everything NOT in this table — including Monitoring, Logging, Events, Vault, Data Safe, WAF, Cloud Guard, Bastion, management subnets, compartment boundaries — requires explicit user approval via the pre-generation review.
+
 - **Ask, don't guess.** When requirements are ambiguous or incomplete, ask a clarifying question instead of filling in assumptions. A 10-second question saves a 10-minute redo.
- **Pre-generation review.** Before generating any diagram or architecture artifact, confirm the component list with the user. Present what you understood and suggest optional additions they can approve or reject:
-  ```
-  I'll generate a diagram with:
-  ✅ [list of explicitly requested components]

-  Want me to also include any of these?
-  • Observability subnet
-  • Compartment boundaries
-  • Security services (Data Safe, Vault)
-  • Gateways (IGW, NAT, SGW)
-  • [other relevant options based on context]
-
-  Or just generate with the above?
+- **MANDATORY pre-generation review.** Before generating ANY diagram, deck, or architecture artifact, you MUST confirm the component list with the user. Never skip this step. Present three clearly separated sections:
  ```
-  This takes 5 seconds to confirm and prevents rework.
+  I'll generate with:
+
+  REQUESTED (from your input):
+  ✅ [only components explicitly mentioned by the user]
+
+  TECHNICAL DEPENDENCIES (auto-added per whitelist):
+  ⚙️ [only items from the whitelist table above, with reason]
+
+  OPTIONAL — want me to add any of these?
+  ○ Observability (Monitoring, Logging, Events)
+  ○ Security services (Vault, Data Safe, WAF, Cloud Guard)
+  ○ Management subnet
+  ○ Compartment boundaries
+  ○ Bastion / jump host
+  ○ [other relevant options based on context]
+
+  Generate with the above, or adjust?
+  ```
+  Wait for the user's response before generating. If the user says "just generate" or equivalent, proceed with only REQUESTED + TECHNICAL DEPENDENCIES (no optionals).
+
+- **Source attribution.** When the user provides documents, URLs, meeting notes, or external data:
+  - Cite the source when extracting data: "From [document/source]: [extracted fact]"
+  - Clearly separate facts from the source vs. your own inferences
+  - If the source contradicts the internal KB, flag the conflict explicitly and let the architect decide

 ## What You Do NOT Do