---

name: extractor-troubleshooting description: "Troubleshoot Graphify source-format support, language extractors, resolver behavior, node IDs, and extractor-specific graph failures." metadata: disco-role: operating disable-model-invocation: true license: NOASSERTION

Extractor Troubleshooting

Use this sub-skill when a Graphify user or maintainer needs to explain why a file type was or was not extracted, debug language-specific AST output, reason about resolver-created edges, or investigate zero-node/duplicate-ID extractor symptoms.

Start from the root router when the task is not clearly extractor-specific: graphify.

Use this when

• A source file extension is ignored, classified as code without an AST extractor, or requires an optional language extra.
• A .tf, .tfvars, .hcl, .sql, .pas, .pp, .dpr, .dpk, .inc, .dm, .dme, .dmi, .dmm, or .dmf report needs parser/extra guidance.
• A maintainer is adding, migrating, or debugging a language extractor or resolver.
• Graph output has zero-node warnings, duplicate/legacy node IDs, wrong source_file normalization, dangling extractor edges, or same-endpoint edge-collapse risk.
• A focused native test list is needed for language extractor or resolver changes.

Route elsewhere

• Ordinary build, update, cache, manifest, --code-only, or graphify-out/ creation workflow: graph-building.
• Query/path/explain interpretation, user-facing traversal direction, ambiguous query labels, or MCP serving: query-navigation.
• Assistant install, packaged skill, hooks, or always-on troubleshooting: agent-integration.
• Export formats, multi-repo merge, database pushes, affected/god-node command usage outside extractor root-cause analysis: exports-integrations.

Read order

1. references/source-formats.md for extension support, extractor ownership, detection-versus-dispatch distinctions, and optional extras.
2. references/troubleshooting.md for symptom-to-cause diagnosis and safe commands.
3. references/extractor-development.md for maintainer workflows, node-ID/source-file rules, resolver registration, and focused tests.
4. Run scripts/inspect_file_support.py when you need source-free classification and parser-availability evidence for user-provided paths.

Quick diagnostic flow

From the installed runtime skill directory, inspect suspicious paths without executing user code:

python sub-skills/extractor-troubleshooting/scripts/inspect_file_support.py path/to/file.tf path/to/file.pas
python sub-skills/extractor-troubleshooting/scripts/inspect_file_support.py --recursive path/to/repo
python sub-skills/extractor-troubleshooting/scripts/inspect_file_support.py --json path/to/file.dm

Interpretation:

• classification=code plus an extractor=... value means Graphify has an extractor route for that path.
• status=missing_optional_extra means an extractor is wired but a parser package is not importable; install the named graphifyy[...] extra in the same environment that runs Graphify.
• Pascal has two paths: the optional graphifyy[pascal] tree-sitter parser and a regex fallback. Missing tree_sitter_pascal lowers extractor quality but is not a hard unsupported-file result.
• .dmi, .dmm, and .dmf are BYOND side formats handled without tree-sitter-dm; .dm and .dme need graphifyy[dm] for AST extraction.
• status=code_without_ast_extractor means detection calls the file code, but Graphify currently has no AST extractor for that suffix or shebang; open/implement language support rather than telling the user it should appear in the graph.

Maintainer guardrails

• Do not execute user source code to diagnose extraction; Graphify extractors parse/read files only.
• Preserve Graphify's schema: nodes require id, label, file_type, source_file; edges require source, target, relation, confidence, source_file.
• Preserve source -> target semantics. If a user-facing command traverses or renders the reverse direction, route interpretation to query-navigation.
• Use canonical IDs from graphify.ids.make_id / extractor helpers; do not invent a separate normalizer.
• Keep local machine paths out of graph IDs and generated guidance. Extraction relativizes source_file to the scan root and remaps absolute-path-derived IDs.
• Treat optional language extras as optional install variants, not as required accelerator/backend capabilities; no GPU or accelerator backend is required for this maintainer scope.

Focused native candidate

Primary native candidate for this sub-skill: native.language-extractors-core, centered on language extractor and resolver tests. Optional extractor-specific tests should be selected only when a user or maintainer focuses on that extra.