9d739dfa5d
- All gsdDir/gsdRoot/gsdHome → sfDir/sfRootDir/sfHome - GSDWorkspace* → SFWorkspace* interfaces - bootstrapGsdProject → bootstrapProject - runGSDDoctor → runSFDoctor - GsdClient → SfClient, gsd-client.ts → sf-client.ts - .gsd/ → .sf/ in all tests, docs, docker, native, vscode - Auto-migration: headless detects .gsd/ → renames to .sf/ - Deleted gsd-phase-state.ts backward-compat re-export - Renamed bin/gsd-from-source → bin/sf-from-source - Updated mintlify docs, github workflows, docker configs
211 lines
6.8 KiB
Text
211 lines
6.8 KiB
Text
---
|
|
title: "Change management"
|
|
description: "How to handle bugs, new features, and roadmap reshuffling after milestones are underway."
|
|
---
|
|
|
|
Reality diverges from plans. This guide covers every situation where you need to act on something discovered after work is already in flight — from a single bug fix to inserting a whole new milestone before the next planned one.
|
|
|
|
## Mental model
|
|
|
|
SF's pipeline looks like this:
|
|
|
|
```
|
|
M001 complete → M002 complete → M003 → M004 → ...
|
|
```
|
|
|
|
The key invariant: **completed units are sealed.** A finished task, slice, or milestone can't be un-completed. What you can always do is add new work ahead of or after any remaining unit.
|
|
|
|
Between milestones you have the most freedom. Inside a running milestone you have real steering options without breaking the state machine.
|
|
|
|
---
|
|
|
|
## Small bug or quick fix
|
|
|
|
**A self-contained fix that can be described in a sentence.**
|
|
|
|
```
|
|
/sf quick "fix the date formatting bug in the invoice renderer"
|
|
```
|
|
|
|
`/sf quick` executes immediately with full SF guarantees (atomic commit, state tracking) but skips milestone ceremony. It doesn't touch the milestone pipeline.
|
|
|
|
---
|
|
|
|
## Bug or idea discovered while auto-mode is running
|
|
|
|
**You spot something mid-execution but don't want to interrupt the run.**
|
|
|
|
```
|
|
/sf capture "the login redirect is broken on mobile viewports"
|
|
/sf capture "add a loading spinner to the data table"
|
|
```
|
|
|
|
Captures are appended to `.sf/CAPTURES.md` and triaged automatically at natural seams between tasks. See [captures and triage](/guides/captures-triage) for the full classification system.
|
|
|
|
To force processing immediately:
|
|
|
|
```
|
|
/sf triage
|
|
```
|
|
|
|
---
|
|
|
|
## Current slice plan is wrong
|
|
|
|
**You're mid-slice and the plan no longer makes sense — wrong approach, missing step, or a blocker.**
|
|
|
|
```
|
|
/sf steer
|
|
```
|
|
|
|
This opens an interactive session to hard-edit plan documents. Changes are picked up at the next phase boundary without stopping auto-mode.
|
|
|
|
For structural changes (adding tasks, removing tasks), the agent triggers a slice replan internally when it discovers a blocker. Completed tasks are protected — only pending tasks can be mutated.
|
|
|
|
---
|
|
|
|
## Bugs and features need to land before the next milestone
|
|
|
|
**M001 and M002 are done. You've found bugs and have new features that must ship before M003 can proceed.**
|
|
|
|
<Steps>
|
|
<Step title="Triage your list">
|
|
Separate into: bugs vs. features, and must-before-M003 vs. can-wait.
|
|
</Step>
|
|
<Step title="Create a new milestone for the pre-M003 work">
|
|
```
|
|
/sf new-milestone
|
|
```
|
|
Describe the bugs and features. SF creates a milestone — the title is what matters, not the number.
|
|
</Step>
|
|
<Step title="Check and reorder the queue">
|
|
```
|
|
/sf queue
|
|
```
|
|
Confirm the new milestone is queued before M003. Reorder if needed.
|
|
</Step>
|
|
<Step title="Park M003 if it shouldn't run yet">
|
|
```
|
|
/sf park M003
|
|
```
|
|
Parking skips M003 without deleting it. Unpark when ready:
|
|
```
|
|
/sf unpark M003
|
|
```
|
|
</Step>
|
|
<Step title="Run auto-mode">
|
|
```
|
|
/sf auto
|
|
```
|
|
Auto-mode dispatches the next active milestone in queue order.
|
|
</Step>
|
|
</Steps>
|
|
|
|
---
|
|
|
|
## Modifying a not-yet-started milestone
|
|
|
|
**You want to change M003's scope — add slices, remove slices, change the approach — before it starts.**
|
|
|
|
Since M003 hasn't started, its plan files can be edited directly. Use `/sf discuss` to talk through the changes and let SF rewrite the artifacts:
|
|
|
|
```
|
|
/sf discuss
|
|
```
|
|
|
|
> "M003 needs to include the new auth flow we discovered. Can we add a slice for that and remove the old token refresh slice?"
|
|
|
|
Or use `/sf steer` to edit plan files directly.
|
|
|
|
If M003 is partially done (some slices complete), auto-mode calls `reassess-roadmap` automatically after each slice. You can also discuss changes during a pause — SF can add, modify, or remove pending slices without touching the completed ones.
|
|
|
|
---
|
|
|
|
## A milestone needs to step back one position
|
|
|
|
**Your "Milestone 3" is effectively now "Milestone 4" because new work must insert before it.**
|
|
|
|
SF milestone numbers are labels, not positions. Execution order is controlled by the queue, not the ID. The procedure is the same as above: create the new milestone, confirm queue order with `/sf queue`, park M003 if needed.
|
|
|
|
The milestone IDs stay as-is — M003 just executes later. No renumbering needed.
|
|
|
|
---
|
|
|
|
## Many bugs — worth a dedicated bugfix milestone
|
|
|
|
**After M002 you have 10+ bugs across multiple systems. Too scattered for individual quick tasks.**
|
|
|
|
```
|
|
/sf new-milestone
|
|
```
|
|
|
|
Describe the full bug list. SF creates a milestone with slices organized by system or severity. Run it in auto-mode like any other milestone. When done, all bugs land as clean commits with a formal milestone summary — readable as a bugfix release.
|
|
|
|
---
|
|
|
|
## Feature ideas that can wait
|
|
|
|
**Real ideas, but nothing that blocks the current plan.**
|
|
|
|
```
|
|
/sf capture "dark mode toggle on the dashboard"
|
|
```
|
|
|
|
Deferred captures surface during roadmap reassessment. SF can fold them into a later milestone when the timing makes sense. Or queue a dedicated features milestone directly:
|
|
|
|
```
|
|
/sf queue
|
|
```
|
|
|
|
---
|
|
|
|
## Bug in a completed slice
|
|
|
|
**A shipped slice has a bug but it's already sealed.**
|
|
|
|
You cannot un-complete the slice. Options:
|
|
|
|
- `/sf quick` for small fixes
|
|
- A new slice in the next milestone that explicitly patches the bug — reference the original slice in the description
|
|
- `/sf steer` to add a fix task to the current active milestone if you're still inside it
|
|
|
|
The completed slice record is preserved as-is. The fix lands as new work with its own commit and summary.
|
|
|
|
---
|
|
|
|
## An entire milestone went in the wrong direction
|
|
|
|
**M002 is done but the approach was wrong, and M003 builds on it.**
|
|
|
|
<Steps>
|
|
<Step title="Discuss the situation">
|
|
```
|
|
/sf discuss
|
|
```
|
|
Work through what's wrong and what the correction looks like before touching anything.
|
|
</Step>
|
|
<Step title="Create a correction milestone">
|
|
A focused "M002b" or "M002-fix" that refactors or replaces what went wrong. Scope it precisely to the broken parts.
|
|
</Step>
|
|
<Step title="Revise M003 if needed">
|
|
If M003 doesn't depend on the broken parts, trim its scope so it doesn't compound the problem. Fix fully in the correction milestone first.
|
|
</Step>
|
|
</Steps>
|
|
|
|
---
|
|
|
|
## Quick reference
|
|
|
|
| Situation | Command |
|
|
|---|---|
|
|
| Small self-contained fix | `/sf quick` |
|
|
| Thought during auto-mode | `/sf capture` |
|
|
| Force-process captures now | `/sf triage` |
|
|
| Current slice plan is wrong | `/sf steer` |
|
|
| New work must land before next milestone | `/sf new-milestone` + `/sf queue` |
|
|
| Delay a future milestone | `/sf park <MID>` / `/sf unpark <MID>` |
|
|
| Modify a not-yet-started milestone | `/sf discuss` or `/sf steer` |
|
|
| Many bugs → dedicated milestone | `/sf new-milestone` (bugfix scope) |
|
|
| Ideas that can wait | `/sf capture` or `/sf queue` |
|
|
| Check/reorder pipeline | `/sf queue` |
|
|
| Architecture discussion | `/sf discuss` |
|