Specifications

A spec is a requirement, a functional specification or a test case written as a Markdown file and anchored to code symbols. Tracemoor keeps track of the anchors when the code changes, links specs to each other and computes from the links which requirements are implemented and tested.

Specs are optional. Tracemoor works without them, and you can add them at any point, also to an existing codebase. For working knowledge such as plans and decisions, use projectdocs.

Artifacts and types

Each spec is one artifact. An artifact has a type, an ID, a title, a status and a Markdown body. The active profile defines which types exist. The bundled profiles define these:

The ID consists of the type and a random suffix, for example FS-66EP13. Random IDs do not collide when two people create specs at the same time on different machines.

Where the files live

Specs live in the exploration, one folder per type:

<exploration>/specs/
  urs/URS-X32AND.md
  fs/FS-66EP13.md
  tc/TC-K4W4D2.md
  _drafts/          generated drafts, not yet accepted
  _profiles/        imported profiles

The frontmatter holds the structured data, the body holds the prose:

---
id: FS-66EP13
type: FS
title: Current weather retrieval with TTL caching
status: review
anchors:
- src-tauri/src/commands.rs::get_current_weather
- src-tauri/src/cache.rs::WeatherCache
links:
  satisfies:
  - URS-X32AND
  tested_by:
  - TC-K4W4D2
acceptance_criteria:
- An expired cache entry triggers a fresh provider fetch
---
## Description

The system shall return current weather conditions for a coordinate, …

The files are the source of truth. You can read and edit them in any editor and version them with git. Tracemoor reads them into its index with each analysis and with Re-index in the Matrix tab. Changes made in the Specs view are indexed at once. After editing a file outside Tracemoor, click Re-index.

Profiles

A profile is a YAML file that defines the rules for the specs of an exploration: the artifact types and their fields, the link types, the statuses, whether approval needs a signature, and which chain of types makes a requirement complete. Each exploration has exactly one active profile. You can import your own profiles. See Profiles.

Links and the trace chain

Specs refer to each other through typed links. Each link type has an inverse, and Tracemoor evaluates both directions. Storing "FS-66EP13 satisfies URS-X32AND" is equivalent to "URS-X32AND satisfied_by FS-66EP13".

The profile names a trace chain, the sequence of types a requirement must pass through. In the GAMP 5 profile it is URS → FS → TC:

flowchart LR
    U["URS-X32AND<br/>View current weather"] -- "satisfied_by" --> F["FS-66EP13<br/>Weather retrieval with caching"]
    F -- "tested_by" --> T["TC-K4W4D2<br/>Served from cache within TTL"]
    F -. "anchor" .-> S1["commands.rs::get_current_weather"]
    F -. "anchor" .-> S2["cache.rs::WeatherCache"]

A link to an artifact that does not exist is marked suspect.

Anchors

An anchor binds a spec to a code symbol. It is a string of the form <file>::<symbol>, for example src-tauri/src/commands.rs::get_current_weather. The relation is many-to-many: a spec can anchor several symbols, and a symbol can carry anchors from several specs.

Tracemoor resolves each anchor against the code index:

When the file was renamed, Tracemoor finds the symbol again by its name and kind and records an anchor_auto_renamed event. A renamed symbol is not found again. Its anchor shows as missing.

When an anchor is first resolved, Tracemoor stores a hash of the symbol's source. If the source changes later, the anchor becomes suspect. Suspect means that the code behind the spec has changed and someone has to check whether the spec still holds. It does not mean that something is broken. A reviewer confirms the spec with a reason, which stores the new hash. See Anchors.

Anchors can also point to symbols in a reference project. Such anchors never become suspect.

Status workflow

Every artifact has one of five statuses:

stateDiagram-v2
    [*] --> draft
    draft --> review: submit
    review --> approved: approve
    review --> rejected: reject
    review --> draft: send back
    approved --> draft: reopen
    rejected --> draft: rework
    draft --> obsolete
    approved --> obsolete
    rejected --> obsolete

obsolete is final. An artifact cannot move from draft to approved directly. Every status change needs a reason, which goes into the audit trail. Profiles that require electronic signatures ask for a signature when a spec is approved or rejected. See Change the status.

Drafts

A draft is a spec that the AI generated from existing code. Drafts live in specs/_drafts/ and do not count as specs until a person accepts them. Accepting gives the draft a final ID and moves it into the type folder. The frontmatter keeps where it came from (ai_generated, ai_confidence, accepted_from_draft_id). See Generate specs from code.

Evidence

From specs, links and anchors Tracemoor derives:

• the traceability matrix, one row per requirement with its chain and its gaps,
• coverage, the share of code symbols that carry anchors,
• signatures on approved specs,
• the audit trail, a hash-chained log of every change,
• audit bundles, a reproducible export of all of this.

These are described in the section Evidence.

Specs and the AI

The AI reads specs, finds them by meaning and checks before changing a symbol whether a spec is anchored to it. With Brave mode it creates drafts, edits specs and maintains anchors. See Specs and the AI.