On this page

A spec describes what to build; work items track the building. Linking the two means anyone reading the spec can see the work it turned into, and anyone working an item can open the spec it came from.

A spec can link to any number of work items, and a work item to any number of specs. A link is a note about the spec, not a change to it: making or removing one never changes what the article says, adds nothing to its history, and never needs approval, even in a category where changes do.

Links are for your team only. Your clients never see them, only the totals of how far the work has got; see What your clients see.

On the spec: the Work items panel#

Open the article in the editor. The Work items panel in the right-hand column lists every work item the spec links to, newest link first, and its header counts them (2 items). Each row shows the item's number and title, and Archived when the item has been archived.

  • Click an item's number to open it in a drawer over the spec.
  • Click the × at the end of a row (Remove the link to I123) to remove that link. The work item itself is untouched.

Until the spec has a link, the panel says No work items linked yet.

On the work item: the Specs section#

Open a work item. When it is linked to at least one spec, its drawer ends with a Specs section (1 spec, 2 specs) listing each spec's title and its state: draft, published or archived. Click a title to open the spec in the article editor.

The section is read-only: links are made and removed on the spec. It shows only to people who hold a Knowledge Base permission, and only when there is something to show.

You only see what you can open

Both lists respect access. A work item you cannot read is left out of a spec's panel and its count, and a spec you cannot see (another member's draft, or one not shared with you) is left out of an item's Specs section.

Linking a spec to existing work items#

  1. Open the spec in the article editor.
  2. In the Work items panel, click Link work item.
  3. Find the item and select it. Only work items can be chosen, not workstreams.

The link appears at the top of the panel, and in the item's Specs section, straight away. Linking an item that is already linked changes nothing.

You need Create knowledge-base articles and must be able to open both the spec and the work item. You do not need to be able to edit the spec's words: a link is not an edit. See Who can do what.

Creating work items from a spec#

When the work is not in DevStride yet, create it from the spec. Every item made this way is linked to the spec as it is created.

  1. In the Work items panel, click Create work items.
  2. Under Titles, type one work item per line, up to 20 at a time. The counter beside the label shows how many you have (3 of 20).
  3. Under Create under, choose a workstream or parent item for them to go in.
  4. Under Item type, choose the type, or leave Default type for your workspace's default.
  5. Optionally tick Copy the spec's content into each item's description (below).
  6. Click Create 3 work items (the button counts your titles).

The new items are created in the order you typed them, exactly as if you had added each one by hand, so the usual rules apply: you need to be able to add items under the parent you chose, and the type must be one that can go there.

If the spec's stage names a work type, that type is used. The Item type box is locked to it, and a note says so: Specs in Ready for development create Story items. You set the work type for each stage under Spec stages. If that type has since been archived, nothing is created and the dialog says The work type this spec's stage requires is archived or no longer exists; pick another type for the stage first.

Copying the spec's content. With Copy the spec's content into each item's description ticked, every new item starts with the spec's body as its description, so whoever picks up the work has the detail in front of them. It is a copy taken at that moment: later edits to the spec do not change the items, and editing an item's description does not change the spec. The spec's review comments stay on the spec; the highlighted passages they point at are copied as plain text, without the highlights. A spec too long for an item description (over about 100 KB) is refused as a whole, with nothing created, so untick the option or shorten the spec. The option starts unticked each time you open the dialog.

If some titles fail, the rest are still created. The dialog stays open with only the titles that were refused, each with its reason in red. Fix what the reason names (a different parent, say) and click the button again. The items that were created are already in the Work items panel.

Creating work items needs Create knowledge-base articles and Create Items And Workstreams. Without both, the Create work items button does not appear.

When a spec reaches a stage#

When you move a spec into a stage that names a work type, and the spec has no work items yet, the editor asks straight away: Create its work items? This spec is now Ready for development. Create its work items?

The dialog is the same one as above, with the stage's work type already fixed. Fill in the titles and parent and create them, or click Not now to leave it for later; the Create work items button stays in the Work items panel.

The question is asked only:

  • when you change the stage in the editor (a stage set by someone else, by the AI Assistant or through the API never prompts),
  • when the new stage names a work type,
  • when the spec has no linked work items you can see, and
  • when you could create the items yourself (Create knowledge-base articles and Create Items And Workstreams).

Finding specs that still need work items#

On Manage articles, click No work items, the last button in the All / Draft / Published / Archived group. The list then shows only articles with no linked work items, on the tab you are on, so open Specifications to check your specs. Click it again to show everything. Unlike the state buttons, it is an on/off switch, so it works together with whichever state you pick.

It combines with the other filters. Choose a stage as well to answer "which specs are ready for development but have nothing built yet?" It also works while you search. When nothing is left, the list says Every spec here already has work items.

A few things to know:

  • A link to a work item that has since been deleted no longer counts, so the spec appears again. A link to an archived item still counts.
  • A link counts even when it is to a work item you cannot read. Such a spec is left out of the filtered list, although its Work items panel looks empty to you.
  • Reordering articles by dragging is turned off while the filter is on: Clear the "No work items" filter to reorder articles.

Seeing how far a spec's work has got#

Once a spec has linked work items, DevStride adds them up so you can see where the build stands without opening each one. The figures are read from the items themselves each time you open the list or the spec, so they follow the work as items are started, finished, re-dated or re-sized.

In the list of specs#

On Manage articles, the Specifications tab has a Progress column. Each spec shows a small bar, split by colour into done (green), in progress (blue), not started (grey) and ended unfinished (dark grey), and beside it how many items it has and how much is done, such as 4 items · 50%. A spec with no linked work reads No work. Hover the bar to see the counts in words: 2 done, 1 in progress, 1 not started.

A warning chip appears beside the bar when a spec needs attention: No work when nothing is linked to it yet, or Needs attention when some of its unfinished items have no size or no dates. Hover the chip to see each reason, for example 2 unfinished items have no size.

While you search with the search box, the column shows a dash, unless Needs attention (below) is on; clear the search to see the bars again.

On the spec's page#

Open the spec in the article editor. At the top of the Work items panel, above the list of items, the same bar is followed by:

Shows
Status How many items are done, in progress, not started and ended unfinished
Points The points of its linked items, added up
Dates The earliest start date to the latest due date among its items
Unsized Unfinished items with no points and no estimate
Undated Unfinished items with neither a start date nor a due date
Blocked Unfinished items marked as blocked
Last activity When any of its items last changed

The summary updates when you link, unlink or create work items, and when you close an item's drawer after changing it.

What counts#

  • Items that ended unfinished (in a status that ends work without completing it, such as Cancelled) are counted and shown, but they are left out of the percentage done and the date range. A cancelled item due next year does not push the spec's dates out, and it does not hold the percentage down.
  • Only unfinished work is counted as unsized, undated or blocked. A finished item needs neither a size nor a date.
  • Archived and deleted items are left out of every figure.
  • Items you cannot read are left out too, so two people may see different numbers for the same spec.
  • At most the 200 most recently linked items are counted; the summary says so when a spec has more.

These figures are simple counts. To have DevStride's AI judge how well the work matches what the spec says, use Check progress now.

Finding specs that need attention#

On the Specifications tab, switch on Needs attention in the toolbar above the list. The list then shows only specs with no linked work, or with unfinished work that has no size or no dates: the ones a planner should look at before the work can be scheduled. Switch it off to show everything again.

It works together with the state buttons, the stage filter, the category and the search box. It judges at most the first 500 specs that match your other filters.

Letting an automation create the work items#

The Spec Reached a Stage automation trigger runs when a spec moves into a stage, so the work can be created, or the team told, without anyone opening a dialog.

  1. On Automate Workflows, click + Automation.
  2. Under 1. When this happens..., choose Knowledge Base → Spec Reached a Stage.
  3. Under When a spec reaches, choose the stage, or leave Any stage.
  4. Optionally add conditions: Spec Publish State (is equal to / is not equal to a state) and Spec Work Items (already exist / do not exist yet).
  5. Under 2. Then do this:, add a Create Work Item, Send Notification or Call Webhook action. These are the only actions offered, because the trigger hands over a spec, not a work item.
  6. Save it.

In the list, the rule reads When a spec reaches Ready for development.

It runs whenever a spec moves into the chosen stage, however the stage was set: in the editor, by the AI Assistant or through the API. Clearing a spec's stage never runs it.

Linking the new item back to the spec#

On a Spec Reached a Stage automation, Create Work Item has an extra switch: Link the new item to the spec. It is on by default, so each item the automation creates appears in the spec's Work items panel. Switch it off to create the item without a link.

The item's title, type and place come from the action, as in any automation; the stage's work type does not apply to it. If the link cannot be made, the item is still created and the run in Run history says why the link was skipped.

Notifications and webhooks can include the spec's Spec Title, Spec Stage, Spec Previous Stage and Spec Id. The spec's text is never passed to an automation.

Who can switch one on#

Saving a Spec Reached a Stage automation switched on needs Edit any member's knowledge-base articles (shown on the Permissions page as Manage All Kb Articles), as well as the usual automation permissions. The automation runs for every spec in the workspace, drafts and specs not shared with you included, and can send their titles on; this permission is the one that can already see them all.

People without it do not see Spec Reached a Stage in the trigger list. Anyone who can edit an existing one can still switch it off: a save that leaves the automation disabled is always allowed.

For the rest of the automation builder, see Setting up basic automations.

The prompt and an automation can both create items

If an automation creates work items when a spec reaches a stage, the editor still asks Create its work items? when you move a spec into that stage yourself, and says so under its question: An automation may also create work items when a spec reaches {stage}, depending on its conditions. Accepting creates a second set, alongside the automation's, so click Not now when the automation will cover this spec.

When the build differs from the spec: as-built changes#

Work does not always come out the way the spec described. When it doesn't, record an as-built change on the work item. One action keeps the item, its comments and its specs in step:

  • The item's description is replaced with what was built. The old description stays in the item's history.
  • An internal comment on the item, headed As-built change recorded, says what the description said before, what it says now, the reason you gave, and where each linked spec stands.
  • The same note is written into every spec the item links to, so the spec says what was really built.

Recording one#

  1. Open the work item and click Record as-built change in its header.
  2. Under Description as built, edit the description to match what was built. It starts as the current description.
  3. Under Why (optional), say why it was built this way.
  4. Click Record change.

DevStride's AI writes the Before and After summary; the Why is always your own words. If the AI is unavailable, a plain summary made from the start of each description is used instead, so nothing is lost. The dialog then shows the summary, labelled Drafted by DevStride AI or Plain summary, and what happened to each linked spec: written, sent for approval, or Skipped with the reason. If the item links to no spec, it says only the description and a comment were updated.

The button is not offered on Service Desk tickets or archived items, and it is disabled while you have unsaved edits to the description.

Your clients can read the note

The summary and your reason are written into the spec itself, so anyone who can read the spec sees them, including customers on the portal. The dialog reminds you of this. Word the reason for that audience.

What goes into the spec#

The note is added at the end of the spec, under an As-built changes heading (created the first time). Each entry is headed with the date, the work item's number and its title, followed by Before, After and Why. Nothing else in the spec is touched.

Each spec is written with your own access to it, exactly as if you edited it by hand:

Your access to the spec What happens
You can edit it The note goes in live, as its own As-built change entry in the spec's history.
You can edit it, but its category needs approval The note becomes a proposed change and is sent for approval. If it is approved, the note goes in; if it is sent back, the entry ends as Changes requested and the note stays out of the spec; if it is withdrawn or discarded, the spec is out of sync again.
The spec already has an open proposed change The note is not added, so it never joins someone else's unfinished edit. The spec is out of sync.
You cannot edit it, or cannot see it The note is not added. The spec is out of sync. Specs you cannot see are counted, never named.

One spec that cannot be written never stops the others, or the description and comment.

When a spec is out of sync#

A spec is never left out of sync quietly. When the note could not go in, the spec's watchers and its author get an in-app notification: A specification is out of sync: a work item it covers changed, and the as-built note could not be added. The person who recorded the change is not told, nor is anyone who cannot read the spec. If that leaves no one, the people who hold Publish knowledge-base articles are told instead. Clicking the notification opens the spec with its As-built changes section in view. See Watching articles and categories.

Waiting notes show in three places:

  • On the work item, a badge in the item's header: Spec out of sync, or Spec update awaiting approval while a note waits for approval. Click it to open Linked specs, which lists each waiting note with the spec it belongs to. Anyone who can read the item sees the badge; no Knowledge Base permission is needed.
  • In an items table, the Spec Sync column shows the same state as the badge on every row, and the Spec Sync rule in Advanced Filters finds every work item whose spec has fallen behind.
  • On the spec, the As-built changes section of the editor's right-hand column, which counts the waiting notes and opens by itself while any are waiting. Each note links to its work item. When nothing is waiting it says Nothing is waiting on this spec.

Each waiting note shows its state (Out of sync or Awaiting approval), the date, the summary, the reason given and why it was skipped. If you can edit the spec you can act on it:

  • Apply puts the note into the spec, with your access: live, or as a proposed change where the category needs approval. In the editor, your unsaved edits are saved first. Apply is refused while the spec has an open proposed change.
  • Dismiss decides the spec needs no change. You must answer Why does this spec need no change?; your reason is kept with your name. The spec is not touched.

If you cannot edit the spec, the note says Ask author or another editor of this spec to apply or dismiss it, or Waiting for an approver on this spec. Notes from work items you cannot see are counted but not shown.

Letting DevStride check finished work#

With spec checks switched on, DevStride's AI writes an As Built for each finished spec-linked work item, compares it with the spec, and records each difference for your team to accept or fix. It never writes into the spec, so it is separate from the as-built changes above.

What your clients see#

Links are staff-only: the customer Help center never shows a spec's work items, and a client working on a spec draft cannot see or change them.

What clients do see is how far the work has got, as totals only. On the portal's Specs page and on each published spec's page, a spec with linked work shows a progress bar, how many of its items are done (2 of 4 done) and its start and due dates. Every linked item counts towards those totals, including items the client could not otherwise see, but the portal never shows an item's title, number, points, blockers, who is working on it or when it last changed. Items that ended unfinished, and archived items, are not counted, and a spec with nothing left to count shows no bar. See Specs in the customer portal. An as-built note is different: once it is in the spec, it is part of the spec's text, and anyone who can read the spec sees it, including the work item's number and title.

Using the DevStride MCP Server#

AI assistants connected through the DevStride MCP Server can do the same work, with your permissions:

Tool What it does
list_kb_article_work_items The work items a spec links to, and how each link was made: by hand, created from the spec, or by an automation.
list_work_item_kb_articles The specs a work item links to.
link_kb_article_work_items Link a spec to up to 50 existing work items at once. If any of them cannot be found or read, nothing is linked.
unlink_kb_article_work_item Remove one link. The in-app AI Assistant always asks you to approve this call.
create_work_items_from_kb_article Create up to 20 work items under a parent, each linked to the spec, following the stage's work type exactly as the dialog does.
record_as_built_change Record an as-built change on a work item, exactly as Record as-built change does: replace its description, comment, and write the note into each linked spec. Skipped specs are reported, never ignored. The in-app AI Assistant always asks you to approve this call.
list_as_built_entries Where a work item's specs, or one spec's notes, stand: by default only the notes still waiting on someone.
apply_as_built_entry, dismiss_as_built_entry Apply a waiting note to its spec, or dismiss it with a reason. The in-app AI Assistant always asks you to approve an apply.

find_kb_articles with hasWorkItems: "false" finds the specs that have none yet. find_kb_articles and get_kb_article also report each spec's work progress, with the same figures and the same rules as the spec's page, and find_kb_articles with needsAttention: "true" lists the specs that need attention.

Who can do what#

To You need
See a spec's Work items panel, or a work item's Specs section Any Knowledge Base permission, plus access to the spec (and, for each item listed, permission to read it)
See a spec's progress, or use the Needs attention filter Any Knowledge Base permission, plus access to the spec. Only items you can read are counted
Link or unlink a work item Create knowledge-base articles, and access to the spec and the work item. Edit access to the spec is not needed
Create work items from a spec, or be offered them on a stage move Create knowledge-base articles and Create Items And Workstreams, plus the right to add items under the parent you choose
Switch on a Spec Reached a Stage automation Edit any member's knowledge-base articles, plus the automation permissions
Record an as-built change Edit access to the work item and Create Comment. Each spec gets the note only if you could edit it by hand
See a work item's spec badge and Linked specs Permission to read the work item. Notes on specs you cannot see are counted, not shown
Apply or dismiss a waiting note Create knowledge-base articles, plus edit access to the spec
Set a stage's work type Manage Knowledge Base Settings

See Knowledge Base permissions.

Powered by DevStride