From 0b6ca3b7762b7ed861fa1726949bb6a9346d123a Mon Sep 17 00:00:00 2001 From: root Date: Sat, 25 Apr 2026 23:04:26 -0300 Subject: [PATCH] SKILL.md option 2: clarify cached .drawio vs examples/ as references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Diego flagged that Codex, when authoring an absolute_layout, fell back to grepping ``examples/`` for AWS/OCI multicloud patterns even though the procedure said not to. The reason was real: the lookup tool returns a cached ``.drawio`` (canonical Oracle geometry) but no canonical ``absolute_layout.yaml`` template, so the agent had no YAML scaffold to copy the spec shape from. Tighten the rule rather than ban it outright: • Cached ``.drawio`` = GEOMETRY source. Container nesting, padding, AD/subnet placement, icon choices come from there. • ``examples/`` = YAML scaffold reference ONLY (which fields exist, how connections are authored, fontSize unit). Do NOT copy geometry numbers — those came from a different topology. Rule of thumb baked into the SKILL: if you're copying (x, y, w, h) from examples/, stop and copy from the cached .drawio instead. (Codex copy auto-synced via the pre-commit hook installed earlier.) Co-Authored-By: Claude Opus 4.7 (1M context) --- .agents/skills/oci-deal-accelerator/SKILL.md | 5 ++++- SKILL.md | 7 ++++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/.agents/skills/oci-deal-accelerator/SKILL.md b/.agents/skills/oci-deal-accelerator/SKILL.md index f37b18a..da6d6a0 100644 --- a/.agents/skills/oci-deal-accelerator/SKILL.md +++ b/.agents/skills/oci-deal-accelerator/SKILL.md @@ -133,7 +133,10 @@ Pick a number, or just describe what you need. ``` 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 ""` 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. + 1. **Reference-architecture lookup.** Run `python tools/archcenter_pattern_lookup.py ""` 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. + - **The cached `.drawio` is your GEOMETRY source** — it carries Oracle's canonical container nesting, padding, AD/subnet placement, and icon choices. Open it (drawio desktop, drawio.exe, or read the XML) to extract the layout you'll mirror. + - **`examples/` is allowed ONLY as a YAML scaffold reference** — i.e. as a starting `absolute_layout:` skeleton to copy the *spec shape* from (which fields exist, how connections are written, fontSize unit). Do NOT copy *geometry numbers* from `examples/`; those came from a different topology and will produce a worse layout than the canonical Oracle ref. Geometry must come from the cached `.drawio` (or be invented based on it). + - Rule of thumb: if you find yourself copying `(x, y, w, h)` numbers from `examples/`, stop — you should be copying them from (or fitting them to) the cached `.drawio`. `examples/` is a YAML schema reference, not a geometry source. 2. **Pre-generation review.** Confirm the component list with the user (REQUESTED + TECHNICAL DEPENDENCIES per the whitelist). 3. **Author the spec in `absolute_layout` shape** — this is REQUIRED. Do NOT use the legacy workload-driven shape (`tenancy → regions → compartments → services`); it does not resolve OCI icon stencils, does not run through the spec validator, and produces wireframe-looking output (rectangles with text instead of real OCI icons). Every container, service, label, and connection needs explicit `(x, y, w, h)`. 4. **Spec validator runs automatically** before either renderer (`tools/diagram_spec_validator.py`). It runs ONLY on `absolute_layout` specs — that's another reason workload-driven is forbidden. Fix any errors before re-rendering. diff --git a/SKILL.md b/SKILL.md index 0b9548f..ad6df9d 100644 --- a/SKILL.md +++ b/SKILL.md @@ -131,7 +131,10 @@ Pick a number, or just describe what you need. ``` 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 ""` 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. + 1. **Reference-architecture lookup.** Run `python tools/archcenter_pattern_lookup.py ""` 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. + - **The cached `.drawio` is your GEOMETRY source** — it carries Oracle's canonical container nesting, padding, AD/subnet placement, and icon choices. Open it (drawio desktop, drawio.exe, or read the XML) to extract the layout you'll mirror. + - **`examples/` is allowed ONLY as a YAML scaffold reference** — i.e. as a starting `absolute_layout:` skeleton to copy the *spec shape* from (which fields exist, how connections are written, fontSize unit). Do NOT copy *geometry numbers* from `examples/`; those came from a different topology and will produce a worse layout than the canonical Oracle ref. Geometry must come from the cached `.drawio` (or be invented based on it). + - Rule of thumb: if you find yourself copying `(x, y, w, h)` numbers from `examples/`, stop — you should be copying them from (or fitting them to) the cached `.drawio`. `examples/` is a YAML schema reference, not a geometry source. 2. **Pre-generation review.** Confirm the component list with the user (REQUESTED + TECHNICAL DEPENDENCIES per the whitelist). 3. **Author the spec in `absolute_layout` shape** — this is REQUIRED. Do NOT use the legacy workload-driven shape (`tenancy → regions → compartments → services`); it does not resolve OCI icon stencils, does not run through the spec validator, and produces wireframe-looking output (rectangles with text instead of real OCI icons). Every container, service, label, and connection needs explicit `(x, y, w, h)`. 4. **Spec validator runs automatically** before either renderer (`tools/diagram_spec_validator.py`). It runs ONLY on `absolute_layout` specs — that's another reason workload-driven is forbidden. Fix any errors before re-rendering. @@ -565,3 +568,5 @@ KB lives under `kb/`. See [kb/README.md](kb/README.md) for the directory map, fr - You do NOT claim features exist if you're unsure. Check the KB first. - You do NOT do detailed project management. DELIVER artifacts are lightweight handover aids. - You do NOT add services or components the user did not request. + +