domains / software-engineering / codebase-architecture-analysis / ontoly-software-graph

ontoly-software-graph

Skill card

combined

The three copies describe the same core workflow (check for graph, build if missing, check diagnostics, use Ontoly, fall back to source), but each contains material steps or constraints the others lack. The anbeime copy adds a specific 'Answer Shape' and 'Fallback Rules' (e.g., NOT_FOUND handling, disambiguation). The sickn33 copy adds a 'Security & Safety' section, specific CLI verification commands (`ontoly --help`, `find`), and a step to start the MCP server (`ontoly mcp`). The davepoon copy is the most concise but lacks the specific capability names and safety constraints found in the others. Crowning one would hide the specific operational details (like security notes or specific MCP commands) present in the others.

Repositories

Other copies

Combined skill

---
name: ontoly-software-graph
description: Use Ontoly's deterministic Software Graph and MCP capabilities for architecture review, request tracing, dependency analysis, and impact analysis.
---

# Ontoly Software Graph

Use this skill when a coding agent needs evidence-backed software understanding from an Ontoly graph before searching repository files directly.

## Workflow

1. **Verify Availability**: Check for existing Ontoly outputs (`.ontoly/`, `SoftwareGraph.json`, `diagnostics.json`). If the `ontoly` command is unavailable, ask the user to install it or use documented package manager commands.
2. **Build or Refresh**: If no graph exists and the user permits local analysis, run `ontoly build .`. If the project documents a different command, prefer that.
3. **Check Health**: Inspect graph diagnostics, trust score, semantic coverage, framework detection, and validation status. Treat unresolved imports or low trust as answer limitations.
4. **Use Ontoly Capabilities**: Prefer Ontoly CLI or MCP capabilities (e.g., `ExplainArchitecture`, `TraceExecution`, `ImpactAnalysis`) over source file scanning. If MCP is supported, start the server with `ontoly mcp`.
5. **Answer with Evidence**: Structure the answer to include:
   - The direct answer.
   - Graph evidence (node IDs, edge types, file paths, diagnostics).
   - Confidence statement derived from graph evidence.
   - Diagnostics or caveats.
6. **Fallback**: Only inspect source files if the graph is missing, stale, incomplete, or the user explicitly asks for source-level verification. Explain why the graph evidence was insufficient.

## Fallback Rules

- If graph validation fails, report the failure and use source search only to verify the affected area.
- If multiple nodes match a name, ask for disambiguation or show candidates with context.
- If a concept is not in the graph, return `NOT_FOUND` with the closest evidence instead of inventing an answer.

## Security & Safety

- Run Ontoly only on repositories the user is authorized to analyze.
- Do not send graph files, source code, or environment variables to external services unless explicitly permitted.

## Best Practices

- Separate graph facts from inference.
- Rebuild the graph after large user changes before making claims about current architecture.
- Keep fallbacks narrow and explain why they were needed.