Skip to content

skillgen: tell extraction subagents not to emit JSON-Schema keyword nodes - #2256

Open
harshslr wants to merge 1 commit into
Graphify-Labs:v8from
harshslr:fix/json-schema-keyword-extraction-guard
Open

skillgen: tell extraction subagents not to emit JSON-Schema keyword nodes#2256
harshslr wants to merge 1 commit into
Graphify-Labs:v8from
harshslr:fix/json-schema-keyword-extraction-guard

Conversation

@harshslr

Copy link
Copy Markdown

Adds one rule to the extraction subagent prompt: don't emit nodes whose label is a bare JSON-Schema keyword.

Why

A JSON-Schema contract file has no named entities at the keyword level, but nothing in the prompt says so. A subagent handed one emits a node per description / type / $ref / required / properties / enum occurrence — and those recur once per definition, so they arrive in bulk.

On a real corpus (92 files, 669k words) a single 160 KB event-contract schema contributed 362 such nodes and 726 edges — 13% of the graph — which Louvain then grouped into ~12 communities whose entire membership is description ~ $ref ~ type. They swamped the community list and skewed the god-node ranking.

What changed

One rule in tools/skillgen/fragments/references/shared/extraction-spec.md and its compact variant:

JSON-Schema / contract files (*.schema.json, events-*.json, anything with a top-level $schema or $defs): extract the domain the schema describes - event types, payload names, enum values, field semantics, the definitions it composes. NEVER emit a node whose label is a bare schema keyword […]. Link a definition straight to its fields and values (envelope contains event_id, dataClassification contains CUI), never via the keyword that nested them.

The other 28 files are generated: python -m tools.skillgen then python -m tools.skillgen --bless. 30 files, 30 insertions, no deletions.

Relationship to #2255

Same node explosion, other half of the problem. #2255 is the AST path — json_config._is_config_json() treats any JSON with a top-level $schema as a config manifest and walks the whole keyword tree, so the nodes appear even with semantic extraction switched off. That needs a code fix. This PR only hardens the semantic pass, and is useful independently: a subagent can produce these nodes from a schema file the AST extractor correctly skipped.

Testing

tests/test_skillgen.py, tests/test_skill_version_warning.py, tests/test_claude_md.py — 81 passed. The --bless step was required; test_check_passes catches an un-blessed snapshot, which is how I found it.

Note for maintainers

main is ~730 files behind v8 (the default branch) — it has no graphify/extractors/ or tools/skillgen/. Anyone reading the repo tree from main sees a skeleton. Might be worth deleting or clearly marking it; I lost a few minutes to it while researching #2255.

…odes

A JSON-Schema contract file (top-level $schema/$defs) has no named entities at
the keyword level, but the extraction prompt never says so. Subagents reading
one emit a node per `description` / `type` / `$ref` / `required` / `properties`
occurrence — once per definition — and those collapse into communities whose
entire membership is `description ~ $ref ~ type`, polluting clustering, the
god-node analysis and GRAPH_REPORT.md.

Adds one rule to the shared extraction-spec fragment (and its compact variant):
extract the domain the schema describes — event types, payload names, enum
values, field semantics — and link a definition straight to its fields and
values rather than through the keyword that nested them.

Fragment edit + `python -m tools.skillgen` + `--bless`; the other 28 files are
generated. Related to Graphify-Labs#2255, which reports the same node explosion arriving via
the AST path (json_config treats any JSON with a top-level $schema as a config
manifest) — that one is a code fix, this is the prompt half.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant