Add anti-hallucination guardrails and structured data intake to SKILL.md

Fixes two issues: (1) diagrams adding unrequested components (EBS, WAF, Vault,
Monitoring, etc.) by replacing vague "implied dependencies" with a closed
whitelist of 6 technical dependencies and making pre-generation review mandatory
with 3 sections (REQUESTED/TECHNICAL/OPTIONAL). (2) Unstructured data consumption
by adding mandatory Extraction Receipt (CONFIRMED/INFERRED/MISSING), source
tracking in workload profiles, and completeness gate per engagement tier.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
root
2026-04-13 18:02:08 -03:00
parent 635863502d
commit 4e80528d1e
2 changed files with 181 additions and 167 deletions

104
SKILL.md
View File

@@ -252,6 +252,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 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 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. **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.
@@ -285,7 +311,7 @@ Capture enough about current state to architect the future. Frame the problem
1. **Select services** from `kb/services/` across the full OCI catalog 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. 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. 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. 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 6. **Design deployment** — environment strategy, IaC approach, CI/CD pipeline
@@ -308,6 +334,28 @@ Capture enough about current state to architect the future. Frame the problem
#### Confirm (Solution Proposal) #### 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. 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) **Outputs by tier:** See artifact matrix in [docs/engagement-tiers.md](docs/engagement-tiers.md)
@@ -416,23 +464,49 @@ KB lives under `kb/`. See [kb/README.md](kb/README.md) for the directory map, fr
## Guardrails ## 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. - **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? - **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:
• 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?
``` ```
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 ## What You Do NOT Do

View File

@@ -1,26 +1,33 @@
# OCI Deal Accelerator — Architecture Diagram Spec # OCI Deal Accelerator — Architecture Diagram Spec
# Demo: PharmaCorp Mexico — ExaCS dual-region with Data Guard # Demo: PharmaCorp Mexico — ExaCS dual-region with Data Guard
# Prompt 2: Architecture diagram # Layout: Left-to-right flow, ref arch style
# Mexico DC → FastConnect → Queretaro (DB subnet) → DR Sao Paulo
#
# This example only includes components the user explicitly requested:
# ExaCS (prod + DR), Hub-Spoke networking with DRG, FastConnect 10Gbps,
# Bastion in public subnet.
# DRG and Service Gateway are auto-added per technical dependency whitelist.
# Monitoring, Logging, Events, WAF, Vault, EBS — NOT included (not requested).
title: "PharmaCorp Mexico — ExaCS Migration Architecture" title: "PharmaCorp Mexico — ExaCS Migration Architecture"
# External actors # External: Mexico City DC (left side)
external: external:
- id: "mexico_dc" - id: "mexico_dc"
label: "Mexico City\nData Center" label: "Mexico City\nData Center"
icon: "user" icon: "user"
x: 30 x: 30
y: 280 y: 320
w: 50 w: 60
h: 60 h: 70
# OCI Tenancy # OCI Tenancy
tenancy: tenancy:
label: "Oracle Cloud Infrastructure" label: "Oracle Cloud Infrastructure"
x: 280 x: 200
y: 80 y: 60
w: 1500 w: 1650
h: 700 h: 780
regions: regions:
# ── Primary Region: Queretaro ── # ── Primary Region: Queretaro ──
@@ -29,108 +36,61 @@ tenancy:
primary: true primary: true
x: 15 x: 15
y: 40 y: 40
w: 900 w: 1050
h: 640 h: 720
vcns: vcns:
# Hub VCN
- id: "vcn_hub" - id: "vcn_hub"
label: "Hub VCN (10.0.0.0/16)" label: "Hub VCN (10.0.0.0/16)"
x: 15 x: 15
y: 45 y: 45
w: 870 w: 1020
h: 570 h: 650
subnets: subnets:
- id: "subnet_db" # Public subnet — bastion access
label: "Database Subnet (Private) — 10.0.1.0/24"
h: 180
services:
- id: "exacs_prod"
label: "ExaCS X11M\nQuarter Rack\n(EBS + SAP + DW)"
type: "exacs"
w: 180
h: 90
- id: "vault"
label: "OCI Vault\nTDE Keys\n(FIPS 140-2 L3)"
type: "vault"
w: 140
h: 90
- id: "dbmgmt"
label: "Database\nManagement"
type: "monitoring"
w: 120
h: 90
- id: "subnet_app"
label: "Application Subnet (Private) — 10.0.2.0/24"
h: 140
services:
- id: "ebs_app"
label: "EBS R12\nApp Tier\n(2x VM.Standard)"
type: "compute"
w: 160
h: 80
- id: "bastion"
label: "Bastion\nService"
type: "bastion"
w: 120
h: 80
- id: "subnet_pub" - id: "subnet_pub"
label: "Public Subnet — 10.0.0.0/24" label: "Public Subnet — 10.0.0.0/24"
h: 120 h: 120
services: services:
- id: "waf" - id: "bastion"
label: "WAF\n(EBS Web Tier)" label: "Bastion\nService"
type: "waf" type: "bastion"
w: 120
h: 70
- id: "lb"
label: "Load\nBalancer"
type: "load-balancer"
w: 120 w: 120
h: 70 h: 70
- id: "subnet_mgmt" # DB subnet — main workload
label: "Management Subnet (Private) — 10.0.3.0/24" - id: "subnet_db"
h: 110 label: "Database Subnet (Private) — 10.0.1.0/24"
h: 150
services: services:
- id: "monitoring" - id: "exacs_prod"
label: "OCI\nMonitoring" label: "ExaCS X11M\nQuarter Rack\n(Production)"
type: "monitoring" type: "exacs"
w: 120 w: 200
h: 65 h: 90
- id: "logging"
label: "OCI Audit\n+ Logging"
type: "logging"
w: 120
h: 65
- id: "events"
label: "OCI Events\n+ Notifications"
type: "events"
w: 140
h: 65
gateways: gateways:
# Auto-added per whitelist: FastConnect requires DRG
- id: "drg" - id: "drg"
label: "DRG\n(Hub)" label: "DRG"
type: "drg" type: "drg"
w: 100 w: 90
h: 70 h: 60
# Auto-added per whitelist: ExaCS backup requires SGW
- id: "sgw" - id: "sgw"
label: "Service\nGateway" label: "Service\nGateway"
type: "service_gateway" type: "service_gateway"
w: 110 w: 100
h: 70 h: 60
# ── DR Region: Sao Paulo ── # ── DR Region: Sao Paulo (right side) ──
- id: "region_gru" - id: "region_gru"
label: "Region — São Paulo (DR)" label: "Region — São Paulo (DR)"
x: 940 x: 1090
y: 40 y: 40
w: 540 w: 540
h: 450 h: 540
vcns: vcns:
- id: "vcn_dr" - id: "vcn_dr"
@@ -138,92 +98,72 @@ tenancy:
x: 15 x: 15
y: 45 y: 45
w: 510 w: 510
h: 380 h: 470
subnets: subnets:
- id: "subnet_dr_db" - id: "subnet_dr_db"
label: "DB Subnet (Private) — 10.1.1.0/24" label: "DB Subnet (Private) — 10.1.1.0/24"
h: 180 h: 200
services: services:
- id: "exacs_dr" - id: "exacs_dr"
label: "ExaCS Standby\n(Data Guard)\nEBS + SAP" label: "ExaCS Standby\n(Data Guard)"
type: "exacs" type: "exacs"
w: 180 w: 200
h: 90 h: 100
- id: "fsdr"
label: "Full Stack DR\n(FSDR)\nOrchestrator"
type: "fsdr"
w: 140
h: 90
- id: "subnet_dr_backup"
label: "Backup Subnet — 10.1.2.0/24"
h: 120
services:
- id: "obj_storage"
label: "Object Storage\n50TB RMAN\nBackups (DW)"
type: "object-storage"
w: 160
h: 70
# Connections # Connections
connections: connections:
- id: "conn_fc1" # Entry: DC → DRG (FastConnect)
label: "FastConnect\n10Gbps (Primary)" - id: "conn_fc"
label: "FastConnect 10Gbps\n(Dual Redundant)"
type: "network" type: "network"
from: "mexico_dc" from: "mexico_dc"
to: "drg" to: "drg"
- id: "conn_fc2" # DR: ExaCS Prod → ExaCS Standby (Data Guard)
label: "FastConnect\n10Gbps (Redundant)"
type: "network"
from: "mexico_dc"
to: "drg"
- id: "conn_drg_dr"
label: "Remote Peering"
type: "network"
from: "drg"
to: "exacs_dr"
- id: "conn_dg" - id: "conn_dg"
label: "Data Guard\n(Redo Shipping)" label: "Data Guard\n(Redo Shipping)"
type: "data" type: "data"
from: "exacs_prod" from: "exacs_prod"
to: "exacs_dr" to: "exacs_dr"
- id: "conn_vault" # ──────────────────────────────────────────────────────────────
label: "TDE Keys" # OPTIONAL — add if the user approves during pre-generation review:
type: "internal" #
from: "vault" # Security:
to: "exacs_prod" # - id: "vault"
# label: "OCI Vault\nTDE Keys"
- id: "conn_waf_lb" # type: "vault"
label: "HTTPS" #
type: "data" # - id: "waf"
from: "waf" # label: "WAF"
to: "lb" # type: "waf"
#
- id: "conn_lb_ebs" # Observability:
label: "HTTP" # - id: "monitoring"
type: "data" # label: "OCI Monitoring"
from: "lb" # type: "monitoring"
to: "ebs_app" #
# - id: "logging"
- id: "conn_ebs_db" # label: "OCI Audit + Logging"
label: "Oracle Net" # type: "logging"
type: "data" #
from: "ebs_app" # - id: "events"
to: "exacs_prod" # label: "OCI Events + Notifications"
# type: "events"
- id: "conn_fsdr_dg" #
label: "Failover\nOrchestration" # Application tier (only if customer has app servers):
type: "internal" # - id: "ebs_app"
from: "fsdr" # label: "EBS R12 App Tier"
to: "exacs_dr" # type: "compute"
#
- id: "conn_backup" # DR orchestration:
label: "RMAN Backup\n(DW)" # - id: "fsdr"
type: "data" # label: "Full Stack DR (FSDR)"
from: "exacs_prod" # type: "fsdr"
to: "obj_storage" #
# Backup:
# - id: "obj_storage"
# label: "Object Storage\nRMAN Backups"
# type: "object-storage"
# ──────────────────────────────────────────────────────────────