Milestones are generated by AI based on your instructions and architecture. But AI isn’t perfect—sometimes you’ll want to adjust a milestone before executing it.
Why Edit Milestones
The AI Made a Mistake
The generated description might:
- Misunderstand what files are involved
- Propose an approach you disagree with
- Include something you want to exclude
You Have Additional Context
You know things the AI doesn’t:
- Specific business logic that needs special handling
- Dependencies that aren’t obvious from the code
- Team preferences for how something should be done
You Want to Adjust Scope
Sometimes a milestone is:
- Too large — break it into smaller pieces by removing parts
- Too small — add related work you want included
- Missing something — add requirements the AI overlooked
You Remembered Something
By the time you reach Milestone 3, you might realize:
- “Oh, this should also include error handling for X”
- “We need to migrate that config file too”
- “Let’s use a different approach for this component”
Editing lets you incorporate these realizations.
What You Can Edit
When you open a milestone for review, you can edit:
- Description — The detailed instructions for what this milestone accomplishes
- The AI uses this description to generate tasks, so changes here directly affect what gets built
When You Can Edit
You can edit a milestone when:
- The milestone hasn’t started yet (no tasks generated)
- You’re the next active milestone (all prior milestones are merged)
Once tasks are generated, the milestone is “locked” for that execution. To make changes after task generation, you’d need to regenerate.
How to Edit a Milestone
- Click on the milestone to expand it
- Click Review (or the Review card)
- The milestone drawer opens with the description
- Edit the content as needed
- Click Save Changes
Enable Downstream Validation
When saving, you’ll see an option: Validate following milestones
When enabled, checks if your changes affect later milestones. If they do, those milestones are updated with recommendations you can review.
Enable this for significant changes. If you’re just fixing a typo, you can skip it.
Editing Tips
Be Clear About What You’re Changing
If the original says:
“Migrate the user authentication module to the new framework”
And you want to add session handling, make it explicit:
“Migrate the user authentication module to the new framework. Include session management and the remember-me functionality.”
Remove Things You Don’t Want
If the milestone includes something you’ll handle differently:
“Also update the legacy admin panel”
“Focus only on the main user-facing authentication. The admin panel will be handled separately.”
Add Context the AI Lacks
“When migrating the payment processing, note that we use a custom wrapper around Stripe. The wrapper is in lib/payments/stripe_wrapper.py and should be preserved with its interface intact.”
Specify Approaches
If you have a preference for how something should be done:
“Use React Query for data fetching instead of the current Redux async actions. Convert each Redux thunk to a React Query hook.”
Handling Applied Edits
When you edit a milestone and enable downstream validation, may automatically update later milestones. You’ll see these as “Applied Edits.”
When reviewing a milestone with applied edits:
- The milestone shows a badge: “X Edits Applied”
- Click Review Edits to see what changed
- For each edit:
- Keep — Accept the change
- Revert — Restore the original text
- Or use Keep All / Revert All for bulk actions
Applied edits are recommendations. If they don’t make sense for a particular milestone, revert them.
Examples
Adding Missing Functionality
Original:
Migrate the user service to FastAPI. Convert all endpoints and update request/response models.
Edited:
Migrate the user service to FastAPI. Convert all endpoints and update request/response models. Also include the email verification flow—the current verify_email endpoint and related token generation should be migrated with full test coverage.
Narrowing Scope
Original:
Migrate all utility functions from utils/ to Python 3 syntax and add type hints.
Edited:
Migrate utility functions from utils/string_helpers.py and utils/date_helpers.py to Python 3 syntax and add type hints. Exclude utils/legacy/ for now—those will be deprecated rather than migrated.
Specifying Approach
Original:
Convert the AngularJS controllers to React components.
Edited:
Convert the AngularJS controllers to React components. Use functional components with hooks. Do not use class components. For state management, use React’s built-in useState and useContext—do not introduce Redux.
Adding Requirements
Original:
Update the database models to use SQLAlchemy 2.0 syntax.
Edited:
Update the database models to use SQLAlchemy 2.0 syntax. Add Alembic migrations for any schema changes. Use async session management. Ensure all relationships are properly typed.
After Editing
Once you save your changes:
- The milestone is updated
- You can proceed to Generate Tasks
- Tasks are created based on your edited description
- Execute as normal
Your edits are now the authoritative instructions for that milestone.
When Not to Edit
Minor Preferences
For small, recurring preferences (naming conventions, coding style), use Rules instead. Rules apply to all milestones automatically.
Fundamental Changes
If you realize the entire migration approach is wrong, editing individual milestones won’t help. Consider whether your original instructions need revisiting. 
