Tracestitch documentation (source for the TSDOCS knowledge base)
Getting started
- Install Tracestitch from the Marketplace in Jira. To show requirements in Confluence too, connect the app to Confluence on the same site (Atlassian Administration > Apps).
- In a space, open Requirements in the sidebar. A space admin opens Settings, turns
tracking on, ticks the work item types that hold requirements (for example "Requirement"),
and picks an ID prefix such as
PAY-REQ. - Tracestitch reads the space. Existing requirements get IDs in creation order (
PAY-REQ-1,PAY-REQ-2...) and version 1. New ones get the next ID within a minute of being created.
Requirement IDs
IDs never change and are never reused, even when a requirement is deleted or its prefix changes. A new prefix applies to requirements created after the change.
Versions and diffs
A new version is recorded when the summary, the description or one of the extra text fields chosen in Settings changes. Status changes, formatting changes (bold, colours) and Jira re-saving the same text do not count. Open a requirement and pick two versions under History to see the difference: added words in bold, removed words struck through.
Folders
Folders organise requirements in a tree up to eight levels deep. People who can edit work items in the space create, rename, move and delete folders; deleting a folder moves its requirements and subfolders up one level. Settings > "New requirements go to" picks the folder for new ones.
Traceability
Tracestitch reads the links on each requirement:
| Linked work item | Counts as |
|---|---|
| A type listed under "types that are tests" (default: Test, Test Case, Test Plan, Test Execution) | Test |
| A test linked to an implementing work item (shown "via KEY") | Test (turn off in Settings) |
| A type listed under "types that are defects" (default: Bug, Defect) | Defect |
| Another requirement | Related requirement (not counted for coverage) |
| Anything else (story, task, epic) | Implementation |
Settings can limit which link types count (for example only "Implements" and "Verifies"). Scenarios from Great Work's Gherkit app count as tests, with their latest CI result.
Coverage verdicts
| Verdict | Meaning |
|---|---|
| Not covered | No implementation, no tests |
| Tests only | Tests but no implementing work |
| No tests | Implementing work but no tests or BDD scenarios |
| In progress | Both, but some work or tests are not done, BDD scenarios not run, or open defects |
| Failing | At least one linked BDD scenario failed its last run |
| Verified | All implementing work and tests done, BDD scenarios passing, no open defects |
Suspect links (to review)
When a requirement's text changes, every work item linked to it before the change is flagged "to review". On the requirement, the Traceability panel lists them; on a story or test, the panel shows "Changed: v1 to v2" with See what changed and Mark reviewed. People who can edit work items in either space can mark a link reviewed. New links are never flagged.
Traceability matrix
Requirements tab > Traceability matrix: one row per requirement with implementation, tests, BDD results, defects and coverage, filtered by folder, coverage or "only with links to review". Export CSV gives up to 1,000 rows per run.
Baselines
A baseline freezes, for every requirement in a folder (with subfolders) or the whole space, its ID, version, text, status, folder and trace links. Up to 1,000 requirements per baseline. Compare a baseline with another one or with the current requirements to see what was added, removed, changed (with the text diff), moved or re-traced. Baselines can be exported as CSV and deleted by space admins.
JQL
| Field | Example |
|---|---|
reqId | reqId = "PAY-REQ-12" |
reqVersion | reqVersion > 3 |
reqCoverage | reqCoverage = "untested" (values: uncovered, unimplemented, untested, in-progress, failing, verified) |
reqSuspect | reqSuspect > 0 (requirements with links to review, or work items linked to a changed requirement) |
reqTraces | reqTraces > 0 (work items linked to at least one requirement) |
Confluence macro
Insert Requirements (Tracestitch), enter requirement IDs or work item keys separated by commas, and optionally a baseline name to show the requirements as they were in that baseline. Choose whether to show the text. The macro is a block of its own; it never edits the page text. Readers see a requirement only if they can browse it in Jira.
Who can do what
| Action | Needs |
|---|---|
| View requirements, matrix, baselines, coverage | Browse the space (lists only show work items you can see) |
| Folders, move requirements, take baselines, mark links reviewed | Edit work items in the space (reviews: in either space) |
| Settings, rescan, delete baselines, activity log | Administer the space (or Jira admin) |
Without an active subscription
Everything recorded stays readable in Jira. Nothing new is recorded, the Confluence macro shows a notice instead of requirements, and syncing resumes when the subscription is active again.
Data and privacy
Tracestitch runs on Atlassian (no outside servers, no egress). See the privacy policy for what it stores.