raulrgmx/oci-deal-accelerator
1
0
Fork 0
forked from diegoecab/oci-deal-accelerator
Code Pull Requests Activity

Diagram procedure: forbid workload-driven shape, warn at runtime

Browse Source 
The Codex session showed why the workload-driven mode is the wrong
default. Codex authored a spec under
``tenancy → regions → compartments → services`` (the documented
"workload-driven" mode), generated two .drawio files, and reported
success. The output was unusable: services rendered as colored
rectangles with text instead of OCI icon stencils, connector text
went into the edge value (forbidden by the connector-label rule),
and the spec validator never ran because it only fires on
``absolute_layout`` blocks.

Diego: "los drawio son horribles, por que sucede eso?".

Three persistent fixes:

1. SKILL.md option 2 now says ``absolute_layout`` is REQUIRED for
   step 3, calls out workload-driven explicitly as forbidden, and
   explains *why* (no stencils, no validator).

2. docs/skill/output-formats.md § Diagram modes is rewritten — mode
   1 is ``absolute_layout`` (REQUIRED), mode 2 is workload-driven
   (DEPRECATED, back-compat only). Removes the "two acceptable
   shapes" framing that let Codex pick the wrong one.

3. ``oci_diagram_gen.py`` now prints a loud stderr WARNING when a
   spec takes the workload-driven path, naming the procedure docs.
   Catches any agent that skipped reading SKILL.md before generating.

Codex copy synced via ``make sync-skill``.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
root
2026-04-25 22:54:03 -03:00
parent a1ad3a6fa1
commit d86adaf7cc
4 changed files with 31 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
SKILL.md
View File

@@ -133,8 +133,8 @@ 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 "<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.
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.
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.