Best Practices
Recommendations for getting the most out of Tusk
Overview
If you haven’t yet integrated Tusk with your ticketing software, read this documentation. It takes less than 3 minutes to set up.
Using our Linear, Jira, Notion, and GitHub integrations allows you to bring Tusk into your sprint and backlog. This guide will walk you through best practices on:
- Embedding Tusk into your engineering-product-design team’s existing workflow
- Creating issues that result in high-quality pull requests (PRs)
Embed Tusk Into Your Workflow
Engineers Review PRs
Engineers on your team are still owners of the PRs created by Tusk. Ensure that you have a designated engineer review Tusk’s PRs, much like how they would review a co-worker’s PR. This allows you to make sure the code’s quality is up to par.
PR reviews also provide an opportunity to submit feedback to Tusk. If you see something in the PR that needs changing, comment on the diffs to start a review, click Review changes under “Files changed”, set the review to Request changes, and submit it. Tusk will then regenerate code to address your PR review in another commit.
Deploy a Preview URL
Set up a CI/CD platform like GitHub Actions or Vercel for GitHub to deploy a preview URL with every push. The reviewing engineer can then go to the preview URL on the Tusk-created PR to visually verify the frontend changes before merging the PR.
Frontend changes, especially UI improvements, often require a visual verification. Think about how difficult it would be to confirm that your styling changes meet requirements without seeing how it looks on the website or app. The more thorough the review, the fewer unintended changes get deployed to staging or prod.
Connecting Ticketing Software
Integrating Linear or Jira with GitHub allows for efficient tracking of issues, keeping your team aligned on the progress of each issue.
When you assign Tusk an issue using our Linear or Jira integration, Tusk automatically adds the Linear or Jira issue key at the start of the PR’s title (e.g., “[PRO-17] Update copy in Security page”). These integrations link the Linear or Jira issue to the corresponding PR and does bi-directional syncs of the task status.
Set Up GitHub Notifications
Setting up GitHub PR notifications for Slack or email ensures that your team is instantly notified whenever Tusk creates a new pull request. This allows for timely reviews and faster integration of code changes. It’s also quite a magical feeling to have the automated PR pop up in your channel if we have to say so ourselves.
Close Incorrect PRs
Close PRs that are obviously incorrect with a guiding comment. Doing so keeps your repo clean and provides Tusk with feedback. Tusk will remember and apply this feedback when solving future tasks, leading to higher quality PRs over time.
Creating Issues for Tusk
Explain Clearly
The quality of Tusk’s PRs depends heavily on the clarity of an issue’s details. Explain the task in your Linear or Jira issue as if you’re explaining it to a newly-onboarded junior engineer. We don’t require that you write the issue with technical knowledge of the codebase (e.g., naming the util or component to use), though it often helps.
You should provide the acceptance criteria in the issue description. From experience, the “Given-When-Then” formula helps with writing clear acceptance criteria. You want to reduce the number of assumptions that Tusk has to make when reading your issue description.
Include Change Location
You should include the location of the change in question in the issue description. This could refer to the file path in the codebase, or it could be the location in the user interface where the issue occurs or where the new feature should be implemented.
Providing this information will help Tusk understand exactly where to focus its efforts, increasing code correctness and completion speed.
Provide a Screen Recording
For more complex tasks, add a public link to a Loom video, Jam recording, or Bird Eats Bug recording in the issue description. Tusk will extract the video and audio from the screen recording to get more context on the task.
We recommend you narrate your actions (e.g., “When I click on this “Create issue” button, it opens up this “Create new issue” modal) as you are clicking through your app in the recording because the LLM can sometimes miss out on where your cursor is on the screen. If it’s a bug fix, walk through the steps to replicate the bug. If it’s a UI change, show the location of the change and talk about what you expect to see.
Add Image Context
If you’re including images in your issue description, add background context. Explain at a high level what each image shows, whether it’s a screenshot of the current product or a design mock-up from Figma (consider using our Figma integration).
This additional information will make it easier for Tusk to understand the visual elements of your issue, and apply that context to its following inferences.
Provide a Before-and-After
When making UI changes, it’s very helpful to provide a before-and-after image. This gives Tusk a clear idea of what the current state is and what the desired end result should be. Separately, annotating elements that need to be changed (e.g., using a rectangle in Preview) is also helpful to visually communicate your requirements.