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

Skill: kill the lookup-loop time-sink (3 fixes from Codex transcript)

Browse Source 
Root cause observed in a real Codex session: the agent burned ~3min
on `make venv` + 4 sequential `make diagram-lookup` queries trying
to find a non-existent ref-arch (OCI PostgreSQL accessed FROM GCP
via Cross-Cloud Interconnect). The catalog has 123 entries; if two
honest queries can't surface a topology, none exists — but nothing
in the skill said "stop." Three coordinated fixes:

1) Makefile: `make venv` is now idempotent.
   Marker file `.venv/.deps-installed` keyed off `requirements.txt`
   mtime — the second `make venv` in a row is a 26ms no-op (was
   1m53s on a Codex sandbox, paid every turn). Force a rebuild with
   `rm .venv/.deps-installed`.

2) kb/architecture-center/catalog.yaml: new `known_gaps` block.
   Surfaced by the lookup tool as a top-of-output banner whenever
   the (synonym-expanded) query tokens match any one of a gap's
   `triggers` token sets. Two gaps seeded from real engagements:

     - gcp-to-oci-native-services — OCI PostgreSQL/OKE/Cache/etc.
       reached FROM GCP via Cross-Cloud Interconnect (the
       Database@Google Cloud entries are the OPPOSITE direction).

     - newer-oci-services-without-icon — OCI Cache (Redis/Valkey)
       and OCI PostgreSQL post-v24.2-toolkit; no ref-arch, no
       toolkit icon, fall back to generic stencil + explicit label.

   Each gap's `notice:` is a copy-paste recommended composition so
   the agent doesn't have to invent a strategy.

3) tools/archcenter_pattern_lookup.py: detects + surfaces gaps.
   `lookup()` now returns `{"matches": ..., "gaps": ...}`. The
   text printer emits a "⚠ KNOWN GAP — <id>" banner with the
   notice block ABOVE the score-based top-K, so the agent sees
   the stop-and-compose signal before ever scrolling to results.
   YAML output mode mirrors the same shape under `gaps:`.

4) SKILL.md (option 2 step 1) + Codex copy via sync-skill.
   New explicit rule: "Lookup budget: max 2 queries — never loop."
   Documents the gap banner, the closest-3-then-ask fallback, and
   the prohibition against grasping at a 3rd refinement.

Verified manually:
  - GCP+postgresql query → gap fires
  - "redis ha multi-az" → newer-OCI gap fires
  - "exadata cross region data guard" → no false-positive gap

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
root
2026-04-27 10:46:27 -03:00
parent ff77563133
commit 7f8cba7f30
5 changed files with 128 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
SKILL.md
View File

@@ -135,6 +135,7 @@ Pick a number, or just describe what you need.
- **The cached `_template.yaml` is your YAML SCAFFOLD** — auto-extracted from the canonical `.drawio` by `tools/archcenter_drawio_to_template.py`. It carries Oracle's container geometry (region/vcn/ad/subnet bboxes), service positions, and edge waypoints in the `absolute_layout:` shape your spec uses. Copy it as the starting point, rename ids, fill in `type:` for services (the extractor leaves `type: TODO_identify` because the canonical icon TYPE is encoded in stencil bytes — pick the right alias from the renderer's TYPE_TO_ICON), and adapt to the customer's components. Lookup result surfaces it as `cached: yaml=<path>`.
- **The cached `.drawio` is the visual source of truth** if the template extractor missed something — open it (drawio.exe, the SVG companion, or the XML) for the canonical look.
- **Do NOT use `examples/` as a geometry source.** `examples/` is previous user output, not authoritative. The `_template.yaml` covers everything `examples/` was being abused for.
- **Lookup budget: max 2 queries — never loop.** If query 1 returns nothing convincing, run ONE refinement (broader phrasing or different keyword angle), then STOP. Re-querying the catalog 3+ times to find a "better" match is the dominant time-sink in this phase — the catalog has 123 entries indexed once; if two passes can't surface a topology match, none exists. Output of the lookup tool also surfaces a **`⚠ KNOWN GAP`** banner at the top whenever the query touches a documented gap (e.g. OCI-native services accessed FROM GCP via Cross-Cloud Interconnect, or OCI Cache/Redis/PostgreSQL as primary subject). When that banner appears, follow its **Recommended composition** verbatim instead of running more queries — it lists the primitives to combine. When NO gap banner appears AND no top-3 entry matches the topology, present the closest 3 to the user with: *"No exact ref-arch matches. Closest hits are X / Y / Z. I can either base the diagram on the closest of these (geometry transfers, service names don't), or compose from `<list specific slugs / patterns>`. Which?"* — let the user pick the chassis instead of guessing.
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)`.