diff --git a/SKILL.md b/SKILL.md index c59e1ef..28627b5 100644 --- a/SKILL.md +++ b/SKILL.md @@ -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 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. @@ -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 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 @@ -308,6 +334,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) @@ -416,23 +464,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 diff --git a/examples/output-demo-pharma-mx/diagram-spec.yaml b/examples/output-demo-pharma-mx/diagram-spec.yaml index c049d96..df7cc29 100644 --- a/examples/output-demo-pharma-mx/diagram-spec.yaml +++ b/examples/output-demo-pharma-mx/diagram-spec.yaml @@ -1,26 +1,33 @@ # OCI Deal Accelerator β€” Architecture Diagram Spec # 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" -# External actors +# External: Mexico City DC (left side) external: - id: "mexico_dc" label: "Mexico City\nData Center" icon: "user" x: 30 - y: 280 - w: 50 - h: 60 + y: 320 + w: 60 + h: 70 # OCI Tenancy tenancy: label: "Oracle Cloud Infrastructure" - x: 280 - y: 80 - w: 1500 - h: 700 + x: 200 + y: 60 + w: 1650 + h: 780 regions: # ── Primary Region: Queretaro ── @@ -29,108 +36,61 @@ tenancy: primary: true x: 15 y: 40 - w: 900 - h: 640 + w: 1050 + h: 720 vcns: - # Hub VCN - id: "vcn_hub" label: "Hub VCN (10.0.0.0/16)" x: 15 y: 45 - w: 870 - h: 570 + w: 1020 + h: 650 subnets: - - id: "subnet_db" - 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 - + # Public subnet β€” bastion access - id: "subnet_pub" label: "Public Subnet β€” 10.0.0.0/24" h: 120 services: - - id: "waf" - label: "WAF\n(EBS Web Tier)" - type: "waf" - w: 120 - h: 70 - - id: "lb" - label: "Load\nBalancer" - type: "load-balancer" + - id: "bastion" + label: "Bastion\nService" + type: "bastion" w: 120 h: 70 - - id: "subnet_mgmt" - label: "Management Subnet (Private) β€” 10.0.3.0/24" - h: 110 + # DB subnet β€” main workload + - id: "subnet_db" + label: "Database Subnet (Private) β€” 10.0.1.0/24" + h: 150 services: - - id: "monitoring" - label: "OCI\nMonitoring" - type: "monitoring" - w: 120 - h: 65 - - 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 + - id: "exacs_prod" + label: "ExaCS X11M\nQuarter Rack\n(Production)" + type: "exacs" + w: 200 + h: 90 gateways: + # Auto-added per whitelist: FastConnect requires DRG - id: "drg" - label: "DRG\n(Hub)" + label: "DRG" type: "drg" - w: 100 - h: 70 + w: 90 + h: 60 + # Auto-added per whitelist: ExaCS backup requires SGW - id: "sgw" label: "Service\nGateway" type: "service_gateway" - w: 110 - h: 70 + w: 100 + h: 60 - # ── DR Region: Sao Paulo ── + # ── DR Region: Sao Paulo (right side) ── - id: "region_gru" label: "Region β€” SΓ£o Paulo (DR)" - x: 940 + x: 1090 y: 40 w: 540 - h: 450 + h: 540 vcns: - id: "vcn_dr" @@ -138,92 +98,72 @@ tenancy: x: 15 y: 45 w: 510 - h: 380 + h: 470 subnets: - id: "subnet_dr_db" label: "DB Subnet (Private) β€” 10.1.1.0/24" - h: 180 + h: 200 services: - id: "exacs_dr" - label: "ExaCS Standby\n(Data Guard)\nEBS + SAP" + label: "ExaCS Standby\n(Data Guard)" type: "exacs" - w: 180 - h: 90 - - 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 + w: 200 + h: 100 # Connections connections: - - id: "conn_fc1" - label: "FastConnect\n10Gbps (Primary)" + # Entry: DC β†’ DRG (FastConnect) + - id: "conn_fc" + label: "FastConnect 10Gbps\n(Dual Redundant)" type: "network" from: "mexico_dc" to: "drg" - - id: "conn_fc2" - 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" - + # DR: ExaCS Prod β†’ ExaCS Standby (Data Guard) - id: "conn_dg" label: "Data Guard\n(Redo Shipping)" type: "data" from: "exacs_prod" to: "exacs_dr" - - id: "conn_vault" - label: "TDE Keys" - type: "internal" - from: "vault" - to: "exacs_prod" - - - id: "conn_waf_lb" - label: "HTTPS" - type: "data" - from: "waf" - to: "lb" - - - id: "conn_lb_ebs" - label: "HTTP" - type: "data" - from: "lb" - to: "ebs_app" - - - id: "conn_ebs_db" - label: "Oracle Net" - type: "data" - from: "ebs_app" - to: "exacs_prod" - - - id: "conn_fsdr_dg" - label: "Failover\nOrchestration" - type: "internal" - from: "fsdr" - to: "exacs_dr" - - - id: "conn_backup" - label: "RMAN Backup\n(DW)" - type: "data" - from: "exacs_prod" - to: "obj_storage" +# ────────────────────────────────────────────────────────────── +# OPTIONAL β€” add if the user approves during pre-generation review: +# +# Security: +# - id: "vault" +# label: "OCI Vault\nTDE Keys" +# type: "vault" +# +# - id: "waf" +# label: "WAF" +# type: "waf" +# +# Observability: +# - id: "monitoring" +# label: "OCI Monitoring" +# type: "monitoring" +# +# - id: "logging" +# label: "OCI Audit + Logging" +# type: "logging" +# +# - id: "events" +# label: "OCI Events + Notifications" +# type: "events" +# +# Application tier (only if customer has app servers): +# - id: "ebs_app" +# label: "EBS R12 App Tier" +# type: "compute" +# +# DR orchestration: +# - id: "fsdr" +# label: "Full Stack DR (FSDR)" +# type: "fsdr" +# +# Backup: +# - id: "obj_storage" +# label: "Object Storage\nRMAN Backups" +# type: "object-storage" +# ──────────────────────────────────────────────────────────────