Project Understanding

Build the smallest explanation that gives the reader an accurate mental model. Ground every claim in source files, runtime evidence, or an explicitly labeled inference.

Select the mode

Choose one mode from the request and scope:

1. Component — a snippet, function, class, or small file. Answer in chat unless the user requests an artifact.
2. Codebase — a package, directory, or repository. Explain structure, execution paths, configuration, tests, and outputs.
3. Project briefing — explain purpose, current state, history, evidence, reports, data/assets, risks, and how to continue.
4. Indexed exploration — use an existing code-intelligence graph for a large repository or repeated questions, then verify important claims against source.
5. Diagnostic — inspect first, then ask grounded questions that test the reader's understanding.

Combine codebase and project-briefing modes when the request is broad. Do not force repository-scale ceremony onto a small component.

Inspect evidence

1. Read the complete target before explaining it.
2. For repositories, inspect the tree, local instructions, README and docs, manifests/configuration, entry points, tests, generated artifacts, reports, notebooks, data/media, and recent version-control evidence when available.
3. Distinguish:
   • Observed — directly supported by a file, command, test, or graph edge.
   • Inferred — a reasonable interpretation that is not directly demonstrated.
   • Unknown — requires runtime data, an external system, missing files, or user confirmation.
4. Resolve contradictions by preferring executable configuration and current source over stale prose. Report unresolved contradictions.
5. Cite local file paths and symbols near the claims they support.

Use an index without surrendering judgment

Check for .ua/knowledge-graph.json or legacy .understand-anything/knowledge-graph.json. If present, follow references/backends.md to check freshness and query only the relevant subgraph. Also use an already-available GitNexus, Graphify, Gortex, or equivalent query tool when it reduces broad scanning.

Never install, initialize, rebuild, or auto-update an external index merely because this skill triggered. Ask before a potentially expensive indexing run. Treat graph summaries as navigation evidence, not final truth; read the load-bearing source before making precise claims.

If no backend exists, continue with direct inspection. The skill must remain fully useful without external tooling.

Construct the explanation

Always provide:

• A one-to-three-sentence purpose statement.
• A compact mental model: “If you remember one thing…”
• The principal path through the code or project.
• Important evidence and uncertainty.

Add when supported:

• A reading path ordered by dependency or learning value.
• Project vocabulary with both an intuitive definition and its local meaning.
• Entry points, components, ownership boundaries, and data/control flow.
• Third-party libraries and the exact role each plays here.
• Parameters/configuration with type, default, accepted values, units, and constraints.
• Outputs, artifacts, side effects, tests, validation, complexity, edge cases, and gotchas.
• Current status, important decisions, risks, unfinished work, and concrete next steps.
• A purposeful diagram when relationships are materially easier to understand visually. Use $diagramming if available; otherwise provide valid Mermaid or a concise ASCII fallback.
• Five to ten diagnostic questions only when the user asks to be grilled, onboarded interactively, or checked for understanding.

Read references/output-contracts.md for the component, codebase, project-briefing, and diagnostic templates. Scale them rather than filling empty sections.

Artifact policy

• Default to chat for a snippet, small file, or ordinary question.
• Create a durable Markdown document only when the user asks for one, the task is explicit onboarding/documentation, or the repository-scale result will be reused.
• Prefer an existing project convention. Otherwise use docs/PROJECT_EXPLAINED.md for a combined briefing or docs/CODEBASE_EXPLAINED.md for code-only onboarding.
• Do not create an HTML microsite, slide deck, or other secondary artifact unless the user asks or it clearly supplies requested functionality.
• Never overwrite an existing document without inspecting it and preserving relevant content.

Quality gate

Before delivering:

• Confirm the explanation matches the inspected version of the target.
• Confirm every important architectural claim has a file, symbol, test, or graph relationship behind it.
• Check that inferred behavior is labeled and runtime behavior is not presented as observed.
• Check parameters, defaults, metrics, status, and library roles were not invented.
• Ensure the mental model and detailed walkthrough describe the same flow.
• Ensure any diagram includes meaningful success/error branches and does not contradict the prose.
• State what was inspected, what was not verified, and where any artifact was written.