diegoecab/oci-deal-accelerator
1
1
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki 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

6
docs/skill/output-formats.md
View File

@@ -85,10 +85,10 @@ These rules are enforced by `tools/diagram_spec_validator.py` and exist because
### Diagram modes
The diagram generator accepts two spec shapes:
The diagram generator accepts two spec shapes — but only ONE is acceptable for any output an SA shows a customer:
1. **Workload-driven (default)** — `tenancy → region(s) → vcn(s) → subnet(s) → service(s)` plus on-premises and external actors. The generator auto-lays out containers and service blocks. Use this for most customer proposals where you describe the workload abstractly.
2. **`absolute_layout` (fidelity mode)** — explicit `(x, y, w, h)` for every container, service, label, and connection. Use this when the user wants to reproduce an Oracle Architecture Center reference diagram with maximum visual fidelity, or when a layout already exists (e.g. extracted from an official `.drawio`).
1. **`absolute_layout` (REQUIRED for any new diagram).** Explicit `(x, y, w, h)` for every container, service, label, and connection. Resolves real OCI stencils from `kb/diagram/oci-icons.json`, runs through `tools/diagram_spec_validator.py` (geometry rules), and produces output visually consistent with Oracle Architecture Center references. **This is the only mode the standard procedure supports.** Pair it with the ref-arch lookup (`tools/archcenter_pattern_lookup.py`) so geometry derives from a canonical Oracle reference, not invented from scratch.
2. **Workload-driven (DEPRECATED).** `tenancy → region(s) → vcn(s) → subnet(s) → service(s)`. The generator auto-lays out blocks but **does NOT resolve OCI icon stencils** — services render as colored rectangles with text labels, connector text gets baked into edge values (which the connector-label rule forbids), and the spec validator does NOT run. Output looks like a wireframe placeholder, not an architecture diagram. Kept only for back-compat with very old specs; do not author new specs in this shape.
```yaml
absolute_layout: