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:
| Column | Subtitle |
|---|---|
| Prepare | Triage, questions, cycle, breakdown |
| Build | Clears implements, opens PRs, self-reviews |
| Review | You review and merge |
| Done | Finished 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 step | Status | Stage column | Whose turn |
|---|---|---|---|
| New - not triaged yet | To Do | Prepare | Waiting for you when the card shows Start Triage, otherwise Clears working while triage runs |
| Triaged - triage has scored the ticket | To Do | Prepare | Waiting for you when the card shows Run or Answer questions, otherwise Clears working |
| Enriched - Clears has written the spec | Enriched | Prepare | Waiting for you - Review enrichment |
| Product Approved - Clears breaks the story down | Product Approved | Prepare | Clears working |
| Ready For Dev - the breakdown waits for your approval | Ready For Dev | Prepare | Waiting for you - Review breakdown |
| Implementation - Clears writes the code | In Progress | Build | Clears working |
| Open pull requests | Validation | Review | Waiting for you - Review PR / Review PRs |
| Merged work still to validate | Validation | Review | Waiting for you - Mark as done |
| Resolved | Done | Done | Done |
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:
- Clears triages the ticket and gives it a readiness score.
- 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.
- When the score reaches the threshold, the card shows Run.
- 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:
- You create the story on the Board with Create Task, or it comes from your tracker
- 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
- If triage has questions, the card is Waiting for you and shows Answer questions
- Once the story is triaged, the card shows Run. Click it to hand the story to Clears
- The AI agent clones your selected repositories and explores the codebase
- Clarifying questions are generated based on the story description and code analysis
- 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)
- You answer questions by selecting options or typing custom responses
- The AI generates a structured specification with: TL;DR, detailed description, definition of done, and files to change
- The story description is updated with the enriched content
- 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:
- The AI analyzes the approved specification
- Subtasks are generated, each representing a discrete unit of work
- Subtasks are created (in your tracker if connected, or locally in standalone mode)
- The story reporter is notified
- 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:
- 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)
- Creates a feature branch (
- 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"
- The Ticket Panel's AI session tab shows a live stream of what the AI is doing
- The Ticket Panel's Git section lists the branches, commits and pull requests as they are created
- If the AI needs your input during implementation, the card shows Waiting for you
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.
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:
| State | Meaning |
|---|---|
| Clears working | Clears 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 you | Clears needs something from you, such as answers, an approval or a review. The card shows an action button |
| Queued | A run is waiting to start |
| Failed | A run failed. The card describes what went wrong and shows Fix and retry |
| Done | The 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 step | Button |
|---|---|
| To Do - triage hasn't run | Start Triage |
| To Do - triaged and ready for Clears | Run |
| To Do - questions from triage or analysis | Answer questions |
| Enriched - review the generated specification | Review enrichment |
| Ready For Dev - review the subtasks and start implementation | Review breakdown |
| Validation - review the pull requests | Review PR / Review PRs |
| Validation - the work is delivered and waits for you to close it | Mark as done |
| A run failed | Fix 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
| From | To | Trigger |
|---|---|---|
| — | To Do | Story created on the Board with Create Task, or in your tracker |
| To Do | Enriched | You click Run after triage, and the AI completes its analysis and questions |
| Enriched | Product Approved | You click Approve and breakdown to subtasks |
| Product Approved | Ready For Dev | AI generates subtasks |
| Ready For Dev | In Progress | You click Approve breakdown |
| In Progress | Validation | AI completes all subtask PRs |
| Validation | Done | You click Mark as Done after the PRs are merged, or the story is closed in your tracker |
| Any | Cancelled | You 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