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

SKILL.md option 2: explicit format question + numbered procedure steps

Browse Source 
A Codex session showed the gap: option 2's prose asked the user to
describe the architecture but only mentioned the output formats in
passing ("if you want X / if you want Y"), so the agent never asked
which format(s). Codex also skipped the reference-architecture lookup
and went straight to grepping ``examples/`` for pre-existing specs —
``examples/`` is previous user output, not the authoritative Oracle
catalog.

Two persistent fixes for any agent (Claude Code, Codex, Cursor, …):

1. Option 2 now asks two explicit questions in one message and waits
   for both answers before doing anything: (1) describe / paste spec,
   (2) pick output format(s) — drawio, native PPTX, or both.

2. The procedure is restated as a numbered list directly under
   option 2 (no longer a single-sentence reference to
   docs/skill/output-formats.md). Step 1 explicitly says use
   ``archcenter_pattern_lookup.py`` against the catalog and explicitly
   forbids using ``examples/`` as a reference source.

Synced to the Codex copy at .agents/skills/oci-deal-accelerator/SKILL.md
via ``make sync-skill`` so both agents see the same instructions.

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

20
SKILL.md
View File

@@ -120,7 +120,25 @@ Pick a number, or just describe what you need.
### Behavior Rules
- If the user picks **1**, ask: "Paste your discovery notes (meeting notes, emails, whatever you have)."
- If the user picks **2**, ask: "Describe the architecture you want to diagram, or paste a YAML spec if you have one. If you want an editable technical diagram I'll generate `.drawio`; if you want presentation-ready Oracle-style visuals I'll generate a native `.pptx` diagram/slide." Then **follow the standard diagram-generation procedure in `docs/skill/output-formats.md` § Standard diagram-generation procedure (MANDATORY)** — reference-architecture lookup → pre-generation review → spec authoring → automatic spec validator → render → visual verification. Do not skip the lookup step; deriving geometry from a similar Oracle ref arch prevents the subnet-collapse / label-overflow regressions the spec validator now blocks.
- If the user picks **2**, ask **two explicit questions** in one message and wait for both answers before doing anything else:
```
1. Describe the architecture you want to diagram (or paste a YAML spec if you have one).
2. Which output format(s) do you want? Pick one or more:
(a) .drawio — editable technical diagram
(b) .pptx — native Oracle-style PowerPoint diagram/slide
(c) both
```
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.
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.
Full reference: `docs/skill/output-formats.md` § "Standard diagram-generation procedure (MANDATORY)".
- If the user picks **3**, ask: "Describe the architecture or paste the spec. I'll generate the deck with a native OCI PowerPoint diagram when the architecture is structured enough."
- If the user picks **4**, ask: "What services and sizing? (e.g., 'ADB-S 8 OCPU + 2 VMs + FastConnect')"
- If the user picks **5**, ask: "Describe your architecture or paste the spec. I'll run the 5-pillar review." Then follow the WA review flow: