Skip to Content
Tares

How should I split bug fixes into milestones for a documentation website?

Tares plans bug fixes as milestones with acceptance checks, so you end each milestone where a check proves a group of fixes works and your assumptions get confirmed. Split the work by what one check can confirm, not by file or by the order you found the bugs. Each milestone ends with one question from the orchestrator, and the crew then carries on with the next milestone.

How it works

When you run tares factory spec, Claude Code asks you questions and a second model challenges the plan. The result goes into Tares as a spec, a plan, an AGENTS.md for the project and milestones, each with acceptance checks. You see them in the Tickets fold of the project page.

The project walkthrough shows a split you can copy for bug fixes. It started from a pull request with no tests and a few bugs, and the plan had three milestones:

  • M1, tests and CI on the branch. A safety net first: a test framework, unit tests for the logic, and a CI check on every pull request.
  • M2, payout history stays as it was. The bug fixes, grouped by one behavior that a check can confirm.
  • M3, merged and live. The pull request documented, merged into main and running in production.

Inside a milestone, the builder works through the tickets one at a time. For each ticket it makes a branch, does the work and opens a pull request. The reviewer posts a verdict on every pull request. Once the verdict passes and CI is green, the builder merges.

When the crew meets something the plan does not cover, it picks the sensible answer, writes it down as an assumption and carries on. At the end of each milestone, the orchestrator brings you all of its assumptions in one question. That question is the end of the milestone.

Set it up

  1. Make sure Claude Code is signed in and gh has write access to the repo that holds your documentation website. Start Tares and the crew as described in Get started.
  2. Bring up the crew.
tares factory crew up
  1. Plan the project. Put the bugs in your prompt and say that you want milestones, each with acceptance checks you can verify.
tares factory spec "fix the bugs in our documentation website"
  1. Answer Claude Code’s questions. When the plan shows milestones, check each one against these rules:
    • The first milestone puts tests and CI on the branch, so every later fix is checked.
    • Each bug-fix milestone groups bugs that one acceptance check can confirm together. Write the check as something you can observe on the site.
    • The last milestone covers merged and live, so the end of the project is also a check.
  2. Say yes to handing the project to the crew. The orchestrator picks it up and starts a builder for the first milestone.
  3. At the end of each milestone, answer the orchestrator’s question about its assumptions. Keep the ones you agree with. To make an answer stand from now on, say so, for this project or for every project.
  4. Watch progress on the Crew page in the console, at http://127.0.0.1:8787/crew on a local Tares.

What you get

  • A clear stopping point. Each milestone has acceptance checks, so you know when a group of fixes is done instead of guessing.
  • Assumptions confirmed in one place. The crew’s own choices come to you together at the end of each milestone. The project page lists them under Assumptions, each with its tickets and the builder that made it, and records whether you kept it.
  • A record of your answers. The Decisions fold keeps every question the crew asked and your answer in your own words.
  • A plan that can grow. In the walkthrough, the reviewer found smaller issues outside the ticket it was reviewing. The orchestrator turned them into a new ticket and placed it in the second milestone, before the integration tests. A bug you missed does not need a new project.
  • A reviewed trail. Every ticket has a pull request, a review round and a merge state you can read on the Tickets fold.

When something else fits

  • If you have a single, small bug, one milestone with one acceptance check is enough. Do not split it further.
  • If a bug fix needs a step only you can take, such as trusting the repo folder in Claude Code or giving Tares a GitHub token, expect the crew to ask you in the orchestrator’s session. Plan your day around those questions rather than around the milestone boundaries alone.

Still stuck? Get help

Last updated on
Quickstart