Plan a cycle and close it on evidence

This page shows you how to commit a set of requirements to a cycle, start it, and close it on what the PR verifier saw.

Prerequisites

• A project in an organization on the Pro plan or above. See Plans.
• A project you can open. Creating, starting and closing a cycle needs the owner, admin or qa project role. See Roles.
• A GitHub or GitLab repository linked to the project, so that evidence exists. Without one, every done item reads as claimed, and the cycle page says so in a sentence instead of showing a number. See GitHub App and GitLab.

What a cycle records

A cycle is a set of requirements committed at an explicit start and closed with a decision per item. Each cycle has a number, assigned when it is created and never changed, a name, a one-sentence goal, a start and end date, and an optional target in points. Once a cycle starts, its number belongs to it for good: the cycle cannot be deleted, and no later cycle in the project takes that number. A planned cycle that never started can be deleted. The next cycle created takes the project's highest number plus one, so a deleted planned cycle gives its number back only when it held the highest number in the project, and deleting an earlier one leaves that number unused. A project has at most one active cycle at a time, and cycles never span projects.

Each requirement in a cycle is a ledger row. The row records when the requirement joined, why, its effort in points at that moment, and, once the cycle closes, its outcome and a copy of the evidence behind it. The evidence comes from the PR verifier: the latest verification for the requirement that belongs to a merged pull request, graded against the acceptance criteria the requirement has now. Marking a requirement done is not evidence; a merged, verified pull request is. See How PR verification works.

Points come from the requirement's effort estimate: XS is 1, S is 2, M is 3, L is 5 and XL is 8. An item with no estimate is counted, not priced: the cycle shows how many items lack an estimate and never assumes a default.

Create a cycle

Only an owner, admin or QA sees New cycle on the project's Cycles page. The wizard has three steps.

1. Basics

   Give the cycle a name, one measurable goal, a start date and an end date at least four days later, and, if you want one, a target in points. The target is optional and only guides the suggestions in the next step. Beside it, a project on the Team plan shows the typical points shipped by earlier cycles once two have closed; on Pro that slot shows a preview of the Team surface. Click Continue.

2. Select

   Pick requirements by hand under Manual, or switch to Auto-suggest and click Suggest requirements to have Spectrace propose a set from the goal and the target, then add to or trim the proposal. Requirements in Done are not offered. A requirement that already sits in another cycle is marked currently in <cycle>, will move. Click Review draft.

3. Review

   The rail shows the effort in points across the selected items and how many of them have no estimate. Click Create cycle. Spectrace numbers the cycle, adds every selected item as planned, and opens the cycle page.

Until you start it, a cycle is Planned. Any project member except a viewer can add items to it and remove them again, and an owner, admin or QA can edit its name, goal, dates and target. Delete sits beside Edit in the cycle header and stays disabled until every item has been removed, giving Remove every item before deleting the cycle. as the reason. A planned cycle that received carried items from a closed cycle cannot be deleted whatever its item count, and stays disabled with This cycle received carried items from a closed cycle and cannot be deleted., so emptying it does not unlock the button. The dialog names the cycle, says the cycle and its ledger go while the project History keeps a record of the deletion, says whether the number comes back, and states that deleting cannot be undone.

Start a cycle

Starting a cycle freezes the commitment. On a planned cycle, an owner, admin or QA clicks Start cycle and confirms in a dialog that shows what is being promised: how many items are committed and their points against the target, how many are unassigned, how many have no acceptance criteria and so cannot be verified, who holds how many items, and how many items have no effort estimate. Spectrace stores that kickoff summary with the cycle and in the project audit log, and the cycle becomes Active with a count of days left.

Anything added after this point is counted as added mid-cycle and is never merged into the committed count. A project has one active cycle at a time: starting a second one fails with Another cycle is already active. Close it before starting this one.

Add and pull items

What you can do depends on the cycle's phase and your role.

• Planned cycle. Any role except viewer can click Add items and pick from the project's requirements. An item that sits in another planned cycle moves; a developer cannot move an item out of the active cycle.
• Active cycle. An owner, admin or QA can still click Add items, and each item added this way is tagged pulled. A developer sees Pull an unassigned item instead: the list holds only requirements that are unassigned or assigned to them, pulling one assigns it to them, and the item is tagged self-pulled. Pulling an item that belongs to someone else fails with Developers can only pull unassigned items or their own.
• Completed cycle. Nothing can be added or removed.

Removing an item from a planned cycle takes the same roles as adding; removing one from an active cycle takes owner, admin or QA. Requirements in Done cannot be added to any cycle. Every add and remove writes a row to the project audit log, so the project History page records an Added to cycle or Removed from cycle event for the requirement. The row does not name the cycle.

On the cycle page, an item's title carries carried in, pulled or self-pulled when it was not part of the original plan, and blocked with the reference of the first unfinished dependency when it has one. The requirement page shows a matching line naming the cycle the requirement is in and how it got there.

Close a cycle

An owner, admin or QA closes an active cycle with Close cycle. A developer can open the same dialog to see the state of every item, but cannot record decisions or close. The dialog sorts the items into three groups:

1. Shipped with evidence. Read-only. Each row shows the pull request, the commit and the criteria satisfied.
2. Marked done without evidence. Items in Done whose evidence is partial, missing or from before tracking. Choose Accept, Carry or Return for each. Accepting any of them needs one reason for the close, typed once and applied to every accepted item.
3. Not finished. Everything else. Choose Carry or Return for each.

Carry needs an upcoming cycle: the planned cycle with the earliest start date on or after this cycle's start. When there is none, the dialog reads No upcoming cycle to carry into. Create one or return these to the backlog. and offers to create the next cycle. Carrying is never silent: without an upcoming cycle you either create one or return the items.

When you confirm, Spectrace recomputes the classification on the server inside one transaction, so the outcome recorded is what the verifier had recorded when the close ran, not what the dialog showed when it opened. A missing decision fails with Every item that is not shipped with evidence needs a decision. and marks the rows that need one; an accepted item with no reason fails with One reason is required to accept items without evidence.; an item that is not in Done cannot be accepted. Nothing is written until every check passes.

On success the cycle becomes Completed. Every item gets its outcome and a copy of the evidence behind it, carried items appear in the upcoming cycle tagged carried in, returned items leave the cycle, and each accepted item gets a Cycle closed entry in the project History while its requirement page's cycle line names who accepted it and the reason. The cycle records who closed it, when, the reason and your optional notes. The project audit log gets one row for the close, one per accepted and returned item, and two per carried item (removed from this cycle, added to the next).

Read the review

A completed cycle opens on its review, generated from what was recorded rather than typed. For example, a review reads:

Shipped 5 of 12 committed with verified PRs. 2 accepted without evidence by Lin: "QA verified by hand, repo not linked". 3 carried to Cycle 4. 1 returned to backlog. 2 added mid-cycle.

Under it, one line says who closed the cycle and when, the verified share of what was committed, and the points shipped with evidence. Four tiles repeat the numbers (committed at start, shipped with evidence, partial evidence, claimed), and a table lists every item with an outcome pill: With evidence, Accepted, Carried or Returned. Partial evidence, Claimed and Before tracking appear only on cycles that closed before evidence tracking. A row added mid-cycle carries a pulled or self-pulled tag on its title. Shipped rows show the pull request number, the short commit hash and the criteria satisfied out of the total; accepted rows show who accepted them and how the requirement reached Done; carried rows name the cycle they went to.

Export review downloads the same content as a markdown file named cycle-<number>-review.md: the review sentence, the numbers, the item table and the notes, ready for a changelog or a retrospective.

A cycle that closed before evidence tracking existed has no recorded review; its page says so instead of showing numbers.

Roles

Cycles use the project role Spectrace resolves for you; see Roles and permissions.

An organization member with no project membership row resolves to viewer and cannot change a cycle. An organization owner or admin resolves to the matching project role without a membership row.

Plans

Cycles are available on the Pro plan and above. The check runs on the server against the organization that owns the project, and every change on a plan without cycles is refused with Cycles are available on the Pro plan and above. A project that already has cycles keeps them readable after a downgrade, with an upgrade prompt above them; a project with none shows what cycles do and the same prompt.

On the Team plan, the Cycles pages also show two facts: the typical points shipped with evidence, the median over the last five closed cycles, shown once two have closed, and the number of open items with no effort estimate. Per-person lanes, at-risk items and Slack digests belong to the same Team surface and are not built yet; on Pro, the places they go show a preview with an upgrade link, and on Team they show a sentence saying so. The Cycles space in the sidebar lists the current cycle of every project you can open, on every plan, with the upgrade prompt where the plan lacks cycles.

Until paid plans open, nothing offers an upgrade. On a plan without cycles, the Cycles space, the Cycles card on the project board and the Cycles pages do not appear, and a change is refused with Cycles are not included on your plan. A project that already has cycles still shows them, read-only. On Pro, the places the Team surface goes stay empty rather than showing a preview.

What done looks like

After a close, the cycle card on the project's Cycles page reads Completed with the committed and with-evidence counts, the cycle page opens on the generated review, and every requirement that was in the cycle shows a cycle line on its page: shipped with evidence, accepted at close by <name>: "<reason>", returned to backlog, or, for a carried item, the upcoming cycle's name with carried in. If the close fails, the dialog shows the server message (the rows that still need a decision, the missing reason, or the carry error above) and nothing has changed. If every done item reads as claimed, check that the repository is linked and that the pull requests named the requirement; see Check runs and branch protection.

Related

• Move a requirement through workflow stages
• Write acceptance criteria
• Roles and permissions
• Check runs and branch protection