diegoecab/oci-deal-accelerator
1
1
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

SKILL.md option 2: clarify cached .drawio vs examples/ as references

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
root
2026-04-25 23:04:26 -03:00
parent 357dd10670
commit 0b6ca3b776
2 changed files with 10 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.agents/skills/oci-deal-accelerator/SKILL.md
View File

@@ -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**: 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. 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.
- **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). 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)`. 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. 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.

7
SKILL.md
View File

@@ -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**: 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. 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.
- **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). 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)`. 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. 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 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 do detailed project management. DELIVER artifacts are lightweight handover aids.
- You do NOT add services or components the user did not request. - You do NOT add services or components the user did not request.
<!-- test marker for sync hook -->