ontoly-software-graph

# Ontoly Software Graph Use this skill when a coding agent needs evidence-backed software understanding from an Ontoly graph before searching repository files directly. ## When to Use - Explaining a repository architecture - Tracing a request, route, controller, service, or dependency path - Finding owners of services, modules, routes, configuration, or environment variables - Reviewing dependency impact before a refactor - Auditing dead code, cycles, unresolved imports, graph quality, or semantic coverage - Preparing documentation, onboarding notes, or architecture review from graph evidence ## Required Workflow 1. Check whether an Ontoly graph already exists by looking for `.ontoly/`, `SoftwareGraph.json`, `diagnostics.json`, validation reports, or an Ontoly MCP configuration. 2. If no graph exists and the user permits local analysis, run: ```bash ontoly build . ``` 3. Inspect graph health before answering: diagnostics, graph hash, semantic coverage, trust or quality score, framework detection, and generation timestamp. 4. Prefer Ontoly CLI or MCP capabilities for graph questions instead of scanning source files first. 5. Use repository search only when Ontoly cannot answer, the graph is stale, the graph is incomplete, or the user explicitly asks for source-level verification. 6. Always cite graph evidence in the answer: node IDs, edge types, file paths, source locations, diagnostics, or framework analyzer output. 7. State confidence from graph evidence. Do not guess confidence. ## Useful Ontoly Capabilities - `ExplainArchitecture` for repository and package topology - `FindDependencies` for dependency trees and direct consumers - `ImpactAnalysis` for refactor blast radius - `TraceExecution` for request, route, and call-flow tracing - `FindConfigurationUsage` for configuration and environment variable usage - `FrameworkReport` for detected framework concepts such as modules, controllers, providers, and routes - `FindDeadCode` for unreachable or unused graph regions ## Answer Shape When answering, include: - the direct answer - graph evidence - confidence - diagnostics or caveats - fallback source inspection only if needed Example: ```text AuthController handles authentication. Evidence: - node: class:src/auth/auth.controller.ts:AuthController - route edges: HANDLES POST /login, POST /logout - dependency edges: USES AuthService, JwtService Confidence: high, because the graph has controller, route, and dependency edges with source locations. ``` ## Fallback Rules - If the graph is missing, build it first when allowed. - If graph validation fails, report the failure and use source search only to verify the affected area. - If multiple nodes match the same name, ask for disambiguation or show the candidates with package/module context. - If the requested concept is not in the graph, return `NOT_FOUND` with the closest graph evidence instead of inventing an answer.