Traceability
The Links panel in every artefact flyout: join a story to the requirement it implements, a bug to the story that fixes it, a decision to the epic it shapes, read each link from either side and open the other end.
By the end of this page you will have joined the artefacts of a project into one record that can be followed in both directions: from a requirement to the stories that implement it, from a story to the rules it honours and the decisions it builds on, from a bug to the story that fixes it; you will know every kind of link, what each reads like from either side, and what a link announces.
A link joins two artefacts of the same project with a kind that is read from the source: CRM-142 implements CRM-FR-12. Opened from the other end, the same link reads the other way: CRM-FR-12 is implemented by CRM-142. Nine kinds of artefact can be linked: epics, work items, requirements, business rules, use cases, RAID items, decisions, data entities and glossary terms. Every link lives in the Links panel at the foot of the artefact's flyout, on every page that has one, so the record is read where the work is read. The panel is internal: a client guest never sees it, even on an artefact the guest may read. The traceability matrix that draws every link of a project on one grid lands with the test module; until then this panel and the API are the record.
Before you begin
| You need | Where it comes from |
|---|---|
| A project with two artefacts | Anything from the planning pages or the dictionary: a link needs two ends in the same project. |
link:view-any | To see the panel and its rows; business analysts, project managers, developers, QA and viewers have it. |
link:create and link:delete | To add and remove links; the roles that write planning artefacts have both. |
Open the links of an artefact
- Open the artefact's page and open the artefact: its flyout opens from the row's menu, from
View, or from a
?show=link someone sent you. - Scroll to Links, below the artefact's versions.
Each row is one link read from this side: a badge with the phrase (implements, is blocked by), a badge with the kind of the other artefact, the other artefact's key and title, the note when one was written, and a remove button when you may remove links. When nothing is linked yet the panel says so; every tree starts with one branch.
Add a link
- Press Add Link. The form opens inside the panel.
- Pick the Relation: how this artefact relates to the one you are about to pick, read from here. The hint under the field reads the sentence back to you.
- Pick the Kind of Artefact the other end is.
- Type at least two characters of its key or title into Find It. The matches of that kind appear under the field, the artefact you are on left out; pick one under Link To.
- Write a Note when the relation alone does not say why, and press Link.
The row appears at the top of the list, a toast confirms the sentence that was written, and
link.created goes out. Cancel closes the form and forgets what was typed.
Three links are refused with a message: the same link twice (the same two ends with the same kind, in either direction for relates to and duplicates, which read the same from both sides), an artefact linked to itself, and an artefact of another project. Anything else the picker offers can be linked.
Open the other end
The key and title of each row are a link: it opens the other artefact's page with that artefact's flyout open, so a requirement's stories, a story's rules and a bug's fix are each one click away. Opened there, the same link is read from that side, with the phrase turned around.
Remove a link
Press the remove button at the end of a row. The link goes, link.deleted goes out, and both
artefacts stand as they were: removing a link never touches either end. There is no confirmation,
because a link removed by mistake is added back in a few seconds and nothing else was lost.
All the fields
The kinds of link
| Read from the source | Read from the target | Use it for |
|---|---|---|
| implements | is implemented by | A story implements a requirement or a use case. |
| derives from | is refined by | A requirement derives from a business rule or an epic. |
| verifies | is verified by | A test case or a criterion verifies a requirement or a rule. |
| covers | is covered by | A test case covers a story or a use case flow. |
| depends on | is depended on by | The source cannot finish before the target does. |
| blocks | is blocked by | The source stops the target from moving until it is done. |
| relates to | relates to | The two belong together without one owning the other. |
| duplicates | duplicates | The two say the same thing; keep one and close the other. |
| is caused by | causes | A bug caused by a decision, an issue caused by a risk. |
| is fixed by | fixes | A bug fixed by a story. |
| supersedes | is superseded by | The source replaces the target, which stays for the record. |
The status reference lists the codes the API and the tools use for each kind.
What happens next
link.createdandlink.deletedgo out with both ends' types and ids, the kind and the project, so a board, a wiki or a pipeline can keep its own picture in step; see thelink.*events.- A link is not a version of either artefact and is never edited in place: to change its kind, remove it and add the right one. Neither artefact's versions change when a link is added or removed, and the two events are the record of who linked what.
- Heimdall and an agent connected over MCP read the links before they draft or build, so a story's requirements, rules and decisions reach them without being pasted; the context pack of a story will carry them when it lands.
- The traceability matrix, the coverage columns and the dependency graph of later modules are all read from this one table: a link made today is drawn there without being made again.
Managing
- Change a kind by removing the link and adding it with the right relation; the two events say what changed.
- An artefact deleted takes its links out of every list on both sides.
- A client guest never sees the panel, whatever the artefact: links name internal items and stay internal.
- Many links at once are made over the REST API or by an agent with
link_artefacts; the panel is one at a time on purpose.
Heimdall on this page
Heimdall reads the links of an artefact when it drafts for it or answers about it, and an agent connected over MCP links what it implements as it works. Neither draws links on its own: a link is a claim about the record, and the panel keeps that claim with the person who makes it.
From the API and MCP
Links API
List an artefact's links, link two artefacts, remove a link.
list_links
Every link that touches one artefact, both ends named, read from that side.
link_artefacts
Join two artefacts of a project with a kind; a repeat is refused.
link.* events
link.created and link.deleted, with both ends and the kind.
Permissions
| Action | Permission |
|---|---|
| See the links | link:view-any and link:view on the project; never a client guest |
| Add a link | link:create |
| Remove a link | link:delete |
Frequently asked
Related
- Backlog — the stories, bugs and tasks most links start from
- Functional requirements — what the stories implement
- Business rules — what the stories honour
- Decisions — what the epics build on
- Status reference — every kind with its code
link.*webhook events
How is this guide?
Last updated on
Decisions
The Decisions page of a project: every choice the project made with its kind, context, the options weighed, what was decided, the consequences, who decided and when, the decision it supersedes, the lifecycle from proposed to accepted and the versions.
Comments and mentions
The Discussion panel in every artefact flyout: ask and answer in threads, name people with @ to tell them, keep a comment internal, resolve a thread, and follow an artefact to hear of every comment on it.