update-solution-analyzer - SKILL.md Agent Skill

name: update-solution-analyzer description: "MANDATORY guidelines for ANY edit to ANY file under Tools/Solutions Analyzer/ — including the mapper (map_solutions_connectors_tables.py), doc generator (generate_connector_docs.py), interactive docs (generate_interactive_docs.py), ASIM browser, collect_table_info, collect_asim_fields, upload_to_kusto, compare_runs, solution_analyzer_overrides.csv, filter_field_resolution.yaml, or any other script/config in that folder. Use when: editing/modifying/refactoring/fixing/renaming/tweaking ANY logic in those files, even one-line fixes such as renaming a classification, escaping a character, adjusting a regex, adding an override row, suppressing a false positive, or changing a constant. Covers: keeping script-docs in sync, README Version History changelog rules (required for feature/behavior changes; optional for small bug fixes), CSV output sync with upload_to_kusto.py, static/interactive index synchronization, and markdown/HTML entity page synchronization."

Update Solution Analyzer Scripts

Before Modifying a Script

Always review the relevant script documentation in Tools/Solutions Analyzer/script-docs/ first. For changes to a CSV output file's columns or semantics, also review the corresponding per-CSV reference page in Tools/Solutions Analyzer/script-docs/csv/ (one file per CSV).

Script Documentation Updates

When updating a script, update the corresponding doc in script-docs/ to reflect:

Script parameters added or changed
Output file changes — for new/renamed/removed CSV columns, edit the per-CSV page in script-docs/csv/<csv-name>.md (the script doc only lists CSVs as a summary table with links; it does not duplicate column tables)
Changes to analysis methods or logic
New CSV output: create a new page under script-docs/csv/, add a row to the summary table in the script doc, and add the new CSV to script-docs/csv/README.md (both the "By generating script" and "By role" sections)

README Changelog

Required for feature additions and behavior changes; optional for small bug fixes. New features, changed analysis logic, new/renamed/removed CSV columns, parameter changes, and other user-visible behavior changes must appear in the changelog. Pure bug fixes — such as correcting a typo, fixing a crash, escape-character tweaks, regex corrections, or one-line fixes that restore intended behavior without changing it — may be logged at your discretion but are not required.

When a changelog entry is warranted, update the ## Version History section in Tools/Solutions Analyzer/README.md:

Add the change under the latest version heading at the top of the changelog
If the latest version has not been committed yet (i.e., it already has uncommitted changes in the changelog), add to that existing version — do not create a new version entry
If the latest version was already committed, create a new version entry with an incremented version number and a short descriptive title
Each entry should be a bullet under a bold category heading (e.g., **Fix Name:**)
Be concise but specific: state what changed, why, and what the user-visible impact is

CSV Output Changes

When adding or removing a CSV output file from the mapper:

Update upload_to_kusto.py → SOLUTION_ANALYZER_FILES list to add/remove the file

Static and Interactive Index Synchronization

The documentation generator produces two parallel sets of index pages that must stay in sync:

Static indexes (generate_connector_docs.py): Markdown index pages — solutions-index.md, connectors-index.md, tables-index.md, content/content-index.md, etc.
Interactive index (generate_interactive_docs.py): HTML page with DataTables.js — index.html with tabs for Solutions, Connectors, Tables, and Content.

When modifying any index generation logic, apply the same change to BOTH:

Data filtering/inclusion rules (which connectors or tables to show)
Status classification logic (Active/Deprecated/Unpublished/Discovered)
Icon usage and legend entries
Special-case handling (placeholder names like <PlaybookName>, "GitHub Only" solution name)
Link generation (collection method links, content item links, parser routing)
Column additions or removals
Description cleanup (quote stripping, truncation)

Markdown and HTML Entity Page Synchronization

The doc generator produces both static markdown and HTML versions of every entity page.

Markdown pages (generate_connector_docs.py): Primary data source — all content, counts, tables, and formatting are defined here.
HTML entity pages (generate_interactive_docs.py → _generate_html_pages()): Auto-generated from markdown via Python markdown library.

In most cases, changing generate_connector_docs.py is sufficient because HTML pages derive from markdown. But if the change involves:

Navigation or link targets
HTML-specific rendering (e.g., DataTables on schema tables)
Heading structure changes

...also update generate_interactive_docs.py.