docs(ai-knowledge-base): add on-demand reference for development for AI Assistants

[hinzzx]

Overview

As a part of the AI Initiative (Skills, Plugins, etc.), we are building a catalog of skills, plugins, and tools that teams can discover and leverage in the projects.

But not everything that guides an AI is a skill or a tool. Some of it is plain instruction: conventions, guardrails, and hard-won facts the assistants needs to write correct code in a given repo.

This contribution is that (second) kind. It is a knowledge base for the UI5 Web Components that AI assistants can load, so the AI produces more efficient and accurate output instead of re-deriving the same facts on every task.

What we add

A new ai-knowledge-base/ folder that documents how code is actually written in the project. It is a plain set of reference files, not a plugin, so an AI assistant (Claude, Cursor, Copilot) or a human reading it gets the same guidance.

The entry point is INDEX.md, that the AGENTS.md file points to.

It carries the non-negotiable rules and a routing table that maps a task ("adding a property", "writing a test", "CSS and theming") to the one reference file that covers it.

The references sit under ai-knowledge-base/references/ and split by concern: API design, component anatomy, core rules, testing, theming, accessibility, i18n, performance, and creating a new component.

What it helps with

It captures the failure modes that no linter reports and that cost real time to rediscover. An event with no doc block is silently private. A class doc block with no @class tag is skipped with no error. A boolean property that defaults to true is rejected by the manifest generator with a misspelled message.

These are the traps that send someone (or the AI Assistant) digging through the framework. They are now written down once.

It also settles the questions that come up on every change. Which mechanism fits, a property or a slot or a method. How to name a boolean so its default is false. Which JSDoc tags pass validation and in what shape. What each lifecycle hook is for.

That means it reduces the reasoning an AI assistant has to do, and the number of wrong guesses it makes, until it comes to the right solution/conclusion. Therefore a cheaper models could potentially be used, for the same level of accuracy of the outputs as models previously needed, that were using higher reasoning effort.

How it saves tokens and time

An assistant without such context explores the codebase to re-derive these facts or search from a compressed memory on every task. It greps for how events are declared, finds two decorator styles, and guesses. That exploration burns tokens and often lands on the wrong or semi-wrong answer.

With the knowledge base, that work collapses into reading one short reference. The load-on-demand design means a typical task pulls the index plus a instruction file/s, a few thousand tokens, rather than the full corpus.

The net effect is fewer tokens spent, fewer wrong guesses, and changes that match the patterns the team already follows instead of the legacy ones scattered through the tree.

Accuracy is the one thing this depends on. The concrete claims were verified against current source. They should be re-checked periodically, since specific references drift as unrelated code changes.

- fewer tokens, fewer wrong guesses, less time exploring, while:
+ more efficient & accurate output

[sap-ui5-webcomponents-release]

🚀 Deployed on https://pr-13909--ui5-webcomponents-preview.netlify.app

[GDamyanov]

This topic is covered in the Cypress tests skill. So this file is redundant

[GDamyanov]

Rules 25, 26, 28 and 29 are redundant.

[GDamyanov]

Suggest adding a rule: Use onEnterDOM/onExitDOM — not connectedCallback/disconnectedCallback — to register and deregister external listeners (ResizeHandler.). This pattern is used consistently across Breadcrumbs, CheckBox, AvatarGroup, StepInput, and others.

[GDamyanov]

Suggest adding: Every document.addEventListener must have a matching document.removeEventListener, and both must live in onEnterDOM/onExitDOM. Button.ts, CheckBox.ts, RangeSlider.ts and SliderTooltip.ts all follow this, but it's easy to forget and not currently called out.

[GDamyanov]

The INDEX.md debugging section already mentions this (handlers that read event.target break when the event crosses a shadow boundary — use composedPath() instead), but core-rules.md has no matching rule. Since this is listed as a non-negotiable in INDEX.md, it should be a Blocking rule here too, with the wrong/right pattern: e.target as ChildElement → e.composedPath()[0] as ChildElement for events that bubble up from child components.