Skip to main content

Story Lifecycle

Every story in Clears AI follows a defined lifecycle - from creation to completion. Each stage represents a meaningful step in the execution pipeline, with automated transitions driven by AI workflows and manual checkpoints where you review and approve.

Lifecycle Overview​

Stages on the Board​

The Board doesn't show one column per status. It has four stage columns:

ColumnSubtitle
PrepareTriage, questions, cycle, breakdown
BuildClears implements, opens PRs, self-reviews
ReviewYou review and merge
DoneFinished and closed

A stage is not a status. The Board places a ticket by what Clears knows about it (triage, runs, pull requests and approvals), not by the status in your tracker. The one exception is a ticket that is closed in your tracker: it is in Done.

Every card also says whose turn it is. This table maps each step of the lifecycle to its stage column and to whose turn it is:

Lifecycle stepStatusStage columnWhose turn
New - not triaged yetTo DoPrepareWaiting for you when the card shows Start Triage, otherwise Clears working while triage runs
Triaged - triage has scored the ticketTo DoPrepareWaiting for you when the card shows Run or Answer questions, otherwise Clears working
Enriched - Clears has written the specEnrichedPrepareWaiting for you - Review enrichment
Product Approved - Clears breaks the story downProduct ApprovedPrepareClears working
Ready For Dev - the breakdown waits for your approvalReady For DevPrepareWaiting for you - Review breakdown
Implementation - Clears writes the codeIn ProgressBuildClears working
Open pull requestsValidationReviewWaiting for you - Review PR / Review PRs
Merged work still to validateValidationReviewWaiting for you - Mark as done
ResolvedDoneDoneDone

A few things move a card for as long as they last:

  • A card in Review shows in Build while a Clears run on it is live, for example while Clears pushes a fix to a pull request. It goes back to Review when the run ends.
  • At any step, a card reads Queued while its run waits to start, and Failed when a run fails.

Triage​

Every ticket starts with triage. Triage scores the ticket's readiness, complexity and risk, and can ask you questions before Clears starts work. The card shows the scores in Prepare.

  • Create Task - when you create a ticket on the Board, Clears starts triage on it if your account's triage settings allow it. You don't need to add a label.
  • Start Triage - shown on a ticket that triage hasn't run on yet. Click it to start triage.
  • Answer questions - shown when triage has questions for you. Answer them in the Ticket Panel's questions step.
  • Run - shown on a triaged ticket that is ready for Clears. Click it on the card to start the run straight away, or open the Ticket Panel's Run step to pick the repositories and skills first.

The Auto Label​

You don't add the auto label yourself. When you run a ticket, Clears adds the label if your account needs it.

On the Board, a ticket goes through these steps before it runs:

  1. Clears triages the ticket and gives it a readiness score.
  2. If the score is below your account's readiness threshold (70% by default), the card shows Answer questions. Clears scores the ticket again after you answer.
  3. When the score reaches the threshold, the card shows Run.
  4. Click Run to hand the ticket to Clears.

When Clears adds the auto label to a ticket with a readiness score above 85%, it first moves the ticket to Product Approved. Triage has already closed the gaps that the analysis questions are for. Clears skips the questions and the specification, and starts the breakdown.

Status Stages​

To Do​

The starting state for every story. The card is in Prepare.

What happens:

  1. You create the story on the Board with Create Task, or it comes from your tracker
  2. Clears triages the story when your account's triage settings allow it. Otherwise the card shows Start Triage, and triage starts when you click it
  3. If triage has questions, the card is Waiting for you and shows Answer questions
  4. Once the story is triaged, the card shows Run. Click it to hand the story to Clears
  5. The AI agent clones your selected repositories and explores the codebase
  6. Clarifying questions are generated based on the story description and code analysis
  7. The card is Waiting for you and shows Answer questions. The questions appear in the Ticket Panel's questions step (and via Slack or Microsoft Teams if connected)
  8. You answer questions by selecting options or typing custom responses
  9. The AI generates a structured specification with: TL;DR, detailed description, definition of done, and files to change
  10. The story description is updated with the enriched content
  11. The story transitions to Enriched

Duration: Typically 2–10 minutes depending on codebase size and number of questions.


Enriched​

The story has been analyzed and a specification has been generated. This is a human checkpoint - you review the AI-generated spec before approving. The card is in Prepare.

What you see:

  • The card is Waiting for you, with the button Review enrichment
  • The Ticket Panel's Review enrichment step, with the enriched description: TL;DR, detailed description, definition of done, and files to change

Your options:

  • Approve and breakdown to subtasks → moves to Product Approved (triggers subtask generation)
  • Cancel story in the Ticket Panel's ⋯ menu → cancels the story

Product Approved​

The spec is approved and the AI begins decomposing the story into implementable subtasks. The card is in Prepare, and it is Clears working.

What happens automatically:

  1. The AI analyzes the approved specification
  2. Subtasks are generated, each representing a discrete unit of work
  3. Subtasks are created (in your tracker if connected, or locally in standalone mode)
  4. The story reporter is notified
  5. The story transitions to Ready For Dev

Duration: Typically 1–5 minutes.


Ready For Dev​

Subtasks have been created and the story is ready for AI implementation. This is another human checkpoint. The card is in Prepare.

What you see:

  • The card is Waiting for you, with the button Review breakdown
  • The Ticket Panel's Approve the breakdown step, with the list of generated subtasks
  • Each subtask with its own description, acceptance criteria, repository and files

Your options:

  • Edit subtasks → rename a subtask, edit its description, or remove it
  • Approve breakdown → approves the breakdown and starts autonomous code implementation

In Progress​

The AI is actively writing code. Each subtask is implemented in sequence. The card is in Build, and it is Clears working.

What happens automatically:

  1. For each subtask, the AI:
    • Creates a feature branch ({ISSUE_KEY}/{slug})
    • Reads relevant code in your repository
    • Writes and commits code changes
    • Creates a pull request (or merge request for GitLab)
  2. The Current activity block on the card shows what Clears is doing right now, including subtask progress such as "Subtask 1 of 2 in progress"
  3. The Ticket Panel's AI session tab shows a live stream of what the AI is doing
  4. The Ticket Panel's Git section lists the branches, commits and pull requests as they are created
  5. If the AI needs your input during implementation, the card shows Waiting for you
note

GitLab uses "merge requests" instead of "pull requests." The Board and the Ticket Panel track both the same way.

What you can do during implementation:

  • Watch progress in the AI session tab
  • Send custom prompts to the AI agent from the AI session tab
  • Respond when the AI pauses for your input

Duration: Varies based on story complexity, from minutes to hours for large stories.


Validation​

Implementation is complete and pull requests are ready for your review. The card is in Review.

What you see:

  • The card is Waiting for you, with the button Review PR (one open pull request) or Review PRs (more than one)
  • The Ticket Panel's Review pull requests step, with each open pull request and its checks
  • Once the pull requests are merged, the card shows Mark as done, and the Ticket Panel shows the Validation needed alert

Your options:

  • Open in GitHub → opens the first pull request so you can check the code, leave comments, or request changes
  • Approve & Merge → approves and merges every open pull request
  • Mark as Done in the Validation needed alert → closes the story when the work is delivered
  • Mark as done in the Ticket Panel's ⋯ menu → the same, from the panel header

Open in GitHub and Approve & Merge are available for GitHub pull requests only. On GitLab or Bitbucket, review and merge the pull requests in your provider.

tip

For GitLab users, "pull requests" in this documentation correspond to "merge requests" in the GitLab UI. The review workflow is the same regardless of your VCS provider.


Done​

The story is complete. All pull requests have been merged and the work is delivered. The card is in Done.

What happens automatically:

  • Learnings from this execution are captured and stored in the memory system
  • Execution context (files changed, decisions made, patterns discovered) is indexed for future reference
  • The memory consolidation process can incorporate these learnings into your global and repository knowledge documents

Cancelled​

A story can be cancelled at any stage that isn't finished, with Cancel story in the Ticket Panel's ⋯ menu. The menu uses your account's name for a story. No further automation runs on a cancelled story.

Whose turn​

While a story moves through its lifecycle, the card says whose turn it is:

StateMeaning
Clears workingClears has a run in progress. The card's Current activity block shows what Clears is doing right now, such as "Subtask 1 of 2 in progress", and updates as Clears moves from step to step
Waiting for youClears needs something from you, such as answers, an approval or a review. The card shows an action button
QueuedA run is waiting to start
FailedA run failed. The card describes what went wrong and shows Fix and retry
DoneThe story is finished

Waiting for you and action buttons​

When it is your turn, the card reads Waiting for you and shows a button for the step you owe. Click it to open that step in the Ticket Panel. The exception is Run, which starts the run straight from the card.

Lifecycle stepButton
To Do - triage hasn't runStart Triage
To Do - triaged and ready for ClearsRun
To Do - questions from triage or analysisAnswer questions
Enriched - review the generated specificationReview enrichment
Ready For Dev - review the subtasks and start implementationReview breakdown
Validation - review the pull requestsReview PR / Review PRs
Validation - the work is delivered and waits for you to close itMark as done
A run failedFix and retry

When a run fails, the Ticket Panel shows the failed run alert, with Dismiss to dismiss the failure and Retry to run it again.

Transition Summary​

FromToTrigger
—To DoStory created on the Board with Create Task, or in your tracker
To DoEnrichedYou click Run after triage, and the AI completes its analysis and questions
EnrichedProduct ApprovedYou click Approve and breakdown to subtasks
Product ApprovedReady For DevAI generates subtasks
Ready For DevIn ProgressYou click Approve breakdown
In ProgressValidationAI completes all subtask PRs
ValidationDoneYou click Mark as Done after the PRs are merged, or the story is closed in your tracker
AnyCancelledYou choose Cancel story in the Ticket Panel's ⋯ menu

Next Steps​

  • Understand how past executions improve future stories in Memory System
  • Learn how to use the Board effectively in Board
  • See every step you can act on in the Ticket Panel