Managing Changes

Every change to the app goes through the workflow, including small ones. That keeps the tests, quality gates and commit history in step with the code.

Why small changes go through the workflow too

If you ask Claude to build, change or fix something outside a running workflow, it points you to /start or /continue rather than editing the code directly. This applies to small requests like “move that button” or “tweak the header” as well.

A change made outside the workflow has no story, no tests and no quality checks. The next epic’s tests may then break on it, or quietly undo it.

Changes while an epic is being built

Describe the change in the chat. Claude adjusts the plan with you and carries on. Plain requests work:

• “I want to update my requirements before we continue.”
• “Redo the stories for this epic. I want to change the scope.”
• “Go back and change the stories for epic 2.”

The manual test is the natural point for changes you only notice once you can use the app. Report what you want changed as part of the test, and Claude fixes it before the epic merges. See Manual Test Checklists.

Changes after an epic has merged

Once an epic is on main, a change becomes new work:

1. Collect the changes: gather all the feedback from the review before acting on any of it.
2. Write them down: describe each change clearly. Work through the wording with Claude if that helps.
3. Group related changes: bundle changes to the same area or flow, rather than handling them one at a time.
4. Start the work: type /start, choose to build something new, and describe the changes. You can also use /plan to plan the change now and build it later.

The change then goes through the same stories approval, build, manual test and merge as any other epic.

Changes to your design

If you built from design files, update them in documentation/ and start a piece of work that names the screens to change. For example: “Rebuild the dashboard and settings screens to match my updated design.”

Only the screens you name change. Decisions you made along the way are kept, so re-reading the design won’t undo them. If the new design contradicts one of your decisions, Claude asks which one to build.

Changes to project-wide facts

Some changes affect the whole project: roles, sign-in, data source, compliance or styling. These live in generated-docs/project.md on main.

If an epic needs one of these facts to change, Claude stops and asks you. Once you agree, Claude updates project.md on main first and then continues the epic, so every later epic inherits the change. You approve the change once.