Concepts¶
This page names the things uncoded deals with, says what each word means, and says how the things relate. It is a page of terms, not an explanation of how uncoded works: the stories say what users do and see, and the architecture says where each thing lives in the code.
The concepts page is an enduring part of the project. Changes to the code, the documentation, the skills and the specifications should keep these meanings, or update this document deliberately.
The product's name is uncoded, in lower case even at the start of a sentence.
Each term has its own entry, which uses only terms explained before it. An entry ends with the words the term replaces. Those words are not used for the concept, in code, documents, skills or issues. Where the code, documents or skills disagree with this document, they are wrong and are corrected to match it.
The dated specifications record the design of particular pieces of work. Where their words conflict with this document, this document is authoritative.
This page replaces "ontology", the name it was first written under.
Terms¶
Project¶
A project is a codebase that is managed with uv and has uncoded as a development dependency.
Replaces: "host project".
Configuration file¶
A project's configuration file is its pyproject.toml, with the uncoded
settings in its [tool.uncoded] table.
Replaces: "config file".
Project directory¶
A project's project directory is the directory that holds its configuration file.
It is not necessarily the top of a Git repository, and a project need not use Git at all. uncoded is not designed for projects nested inside one another, each with its own configuration file.
Replaces: "project root", "repository root".
Python file¶
A Python file is a file whose name ends in .py. Python calls the code in
one a module, and the statements directly in it, not nested in another
statement, its module body.
Symbol¶
A symbol is a named thing that uncoded indexes in a Python file. In the
module body it is a class, a function, a type statement, or an assignment or
annotation whose one target is a bare name, such as x = 1 or x: int.
Directly in a class body it is a method, a property, or such an assignment or
annotation. A property is a method decorated with @property, which uncoded
treats as a property and not as a method.
Each symbol has a name and one definition. Two symbols can share a name, such as
two functions called parse in different Python files. Directories and files
are not symbols, and neither are names defined inside a function, inside a
nested class, or inside another statement such as if or try. This is
narrower than Python's own sense, in which imports and other bindings also name
symbols.
Replaces: "module constant", which is an assignment at module level.
Definition¶
A symbol's definition is the statement that defines it: a class or function
definition, from its first decorator to the end of its body, or an assignment or
type statement. A property's definition is its getter's definition. Its setter
and deleter are neither symbols nor part of its definition.
Replaces: "body" and "source body" for a whole definition. In Python's grammar a body is only the suite after the definition's colon.
Name path¶
A name path identifies a symbol within one Python file. For a symbol at
module level, it is the symbol's name, as greet. For a symbol in a class body,
it is the class's name, a slash and the symbol's name, as Greeter/greet.
uncoded body and uncoded refs take a name path to say which symbol they
mean. Serena, an LSP-based toolkit for agents, uses the same term.
Replaces: "symbol path".
Redefinition¶
A symbol redefines another when it has the same name and is defined later in
the same module body or class body. A name path refers to the later symbol, and
the earlier one cannot be named, as in Python, where the later binding replaces
the earlier. A bare annotation such as x: int binds nothing, but is treated
the same way.
Redefinition is rare, and usually a mistake. An overloaded function is the
common exception: each @overload definition is redefined by the next, and the
last definition, usually the implementation, is the symbol.
The word is the one mypy and pylint use for a name defined again in the same namespace. Shadowing is a different thing: a name in an inner scope hiding the same name in an outer one.
Reference¶
A reference is a place in Python source where a symbol's name stands for that symbol, and not for another symbol with the same name: where the symbol is defined, imported or used.
Heading¶
A heading is a CommonMark ATX heading with non-empty text, outside a fenced code block. uncoded does not index setext headings, which are underlined.
Root¶
A root is a directory or file at the top of a part of a project that uncoded
indexes. The source-roots and doc-roots settings list a project's roots.
Replaces: "root type", for whether a root is a source root or a doc root.
Source root¶
A source root is a directory listed in the source-roots setting. uncoded
indexes the symbols in every Python file beneath it, at any depth.
Doc root¶
A doc root is a directory or a Markdown file listed in the doc-roots
setting. uncoded indexes the headings in that file, or in every Markdown file
beneath that directory, at any depth. A Markdown file is a file whose name ends
in .md. A single file can be a root because its headings form a tree of their
own.
Namespace map¶
The namespace map is the file .uncoded/namespace.yaml. It holds the
symbols of the Python files under the source roots as one tree: directories and
files by their path relative to the project directory, each file's symbols
beneath it, and each class's symbols beneath the class. It lists each file's and
each class's symbols in the order that the Python file defines them, as a stub
does, and a name defined more than once where it is first defined. A file with
no symbols is left out.
Docs map¶
The docs map is the file .uncoded/docs.yaml. It holds the headings of the
Markdown files under the doc roots as one tree: directories and files by their
path relative to the project directory, and each file's headings beneath it,
nested by level. A file with no headings is listed without any.
Replaces: "doc map", "heading map", "heading outline".
Stub¶
A stub is a .pyi file in Python's stub syntax that uncoded writes, for
agents to read, for one Python file that has symbols. It holds the file's
imports from its module body, each class's bases, each function's and method's
signature, and each assignment's annotation and, when short, its value. It lists
the symbols of each module body and class body in the order that the Python file
defines them. It sits at the Python file's path relative to the project
directory, under .uncoded/stubs/.
A stub is laid out in the standard stub style, the layout that ruff and
Black write for .pyi files.
A stub is not a type stub for type checkers. It leaves out parameter defaults and decorators, so a type checker would misread it.
Code index¶
The code index is the namespace map and the stubs.
Replaces: "symbol index".
Documentation index¶
The documentation index is the docs map.
Index¶
The index is the code index and the documentation index together. All its
files are under .uncoded/.
Agent¶
An agent is an AI coding agent working in a project, such as one running in Claude Code or Codex.
Replaces: "coding agent" and "AI coding agent", except to introduce the term.
Recall¶
An agent's recall, when it reads code for a task, is the share of the code relevant to the task that it finds.
Replaces: "sensitivity".
Precision¶
An agent's precision, when it reads code for a task, is the share of the code it reads that is relevant to the task.
uncoded aims to raise both recall and precision, as the stories explain.
Replaces: "specificity".
Skill¶
A skill is a named set of instructions that uncoded generates for an agent to load when its task calls for them.
uncoded skills¶
The uncoded skills are the three skills uncoded generates:
uncoded-code-navigation, uncoded-doc-navigation and
uncoded-consistency-review.
Navigation skills¶
The navigation skills are uncoded-code-navigation and
uncoded-doc-navigation.
Skill source¶
A skill source is the Markdown file in uncoded's package that holds the text of a skill. uncoded adds the skill's name and description when it generates the skill.
Replaces: "package resource", and "skill instructions" or "source" for a skill source.
Installed skill file¶
An installed skill file is a skill's SKILL.md, placed in a project where
agents look for skills.
uncoded writes each skill to .claude/skills/<name>/SKILL.md for Claude Code
and to .agents/skills/<name>/SKILL.md for Codex.
Consistency review¶
The consistency review is the review an agent carries out by following
uncoded-consistency-review. It reports disagreements between two claims about
the same concept, with verbatim evidence for each.
Generated file¶
A generated file is a file that uncoded sync writes in a project: one of
the index's files, an installed skill file, or .uncoded/.gitignore. The
configuration file that uncoded init writes is not a generated file.
Replaces: "artefact", "index artefact", "navigation artefact".
Provenance marker¶
The provenance marker is the text "Generated by uncoded — do not edit;
regeneration overwrites." Every generated file carries it in a comment. The code
defines it once, as GENERATED_MARKER.
Current¶
A project's generated files are current when they are exactly what uncoded would generate from the project as it is now: none missing, none left over, and none with different content. The index is current when its files are.
Replaces: "up to date", "matches a fresh build".
Stale¶
A project's generated files are stale when they are not current. The index is stale when its files are.
Developer¶
A developer is a person who sets up uncoded in a project.
Replaces: "contributor".
User¶
A user is a developer or an agent: anyone who uses uncoded in a project.
Contract¶
uncoded's contract is the part of uncoded that a project can rely on from one release to the next. The compatibility page says what it covers, and which releases can change it.
Replaces: "agent-facing contract".
Relationships and rules¶
This section says how the things above relate. What uncoded does with them, and when, is for the stories.
The project directory¶
Every root, every Python file uncoded is asked about, and every generated file sits inside the project directory.
The index¶
The code index is built from the source roots, and the documentation index from the doc roots. Neither depends on the other.
Each uncoded skill belongs with one part of the index. uncoded-code-navigation
and uncoded-consistency-review belong with the code index, and
uncoded-doc-navigation with the documentation index.
.uncoded/.gitignore keeps the index out of Git: it ignores everything under
.uncoded/, itself included. The installed skill files are meant to be
committed with the project.
Symbols and references¶
A symbol's references include its definition, so every symbol has at least one. A symbol is unused when every reference to it lies within its own definition.
References within the definition of a symbol that it redefines are not uses
either. An unused overloaded function therefore has a reference in each
@overload definition, and is still unused.
Nor are references within a property's setter or deleter uses of the property. An unused property with a setter therefore has references in the setter, and is still unused.