Best practices & troubleshooting
Writing tickets for specs
Include in the description
- The goal and why it matters
- Acceptance criteria and constraints
- Anything out of scope
- Pointers to relevant parts of the code, if you know them
One ticket should map to one coherent change. If a spec grows too large, split the ticket.
Reviewing specs
- Change vs. Recreate: use Change spec for adjustments and Recreate spec when the ticket itself changed fundamentally.
- Read the Tasks tab before applying. It is the plan the AI will follow, and removing or rewording a task is the cheapest way to steer the result.
- Edit directly for small fixes. Use Change spec when several artifacts need to stay consistent.
- After Apply, read the Verify report before you open the code review.
Troubleshooting
| Message | Meaning and fix |
|---|---|
| Git error / push error | The repository could not be cloned or pushed to. Check the URL, base branch, token validity and its write permission. |
| AI error | The AI call failed. Check the credentials, the selected model and, for Bedrock or Foundry, the region or resource. |
| Unregistered installation / insufficient credits | The app is not licensed or registered for this site. Check the app license in Atlassian Marketplace and contact support if it persists. |
| Run takes long | Runs can take up to an hour on large repositories. After that, the panel shows an error and you can retry. |
FAQ
My edits disappeared after Recreate spec.
Recreate spec starts over from the ticket. Use Change spec to keep your edits.
Can I change the spec after applying?
No. After Apply, the spec is locked. Verify, then Finish, and create a new spec for follow-up changes, or fix details in code.
Do I have to run Verify?
No, but it is recommended. Finish works without it.
Support
For help or to report issues, email support@smart-fusion.tech.