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:

   ontoly build .

1. Inspect graph health before answering: diagnostics, graph hash, semantic coverage, trust or quality score, framework detection, and generation timestamp.
2. Prefer Ontoly CLI or MCP capabilities for graph questions instead of scanning source files first.
3. 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.
4. Always cite graph evidence in the answer: node IDs, edge types, file paths, source locations, diagnostics, or framework analyzer output.
5. 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:

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.