Best Practices

​

Overview

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:

1. Embedding Tusk into your engineering-product-design team’s existing workflow
2. 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. This means:

• Grounding the issue description in UI-related terms
• Calling out relevant components/utils/files
• Using quotation marks when referring to labels and copy
• Mentioning pitfalls to avoid

We do not require that you write the issue with technical knowledge of the codebase but it often helps. Make sure to include the expected outcome in the issue description. From experience, the Actual and Expected Results and “Given-When-Then” formats work well with Tusk.

​

Be Concise and Direct

While you want to be detailed when writing your description, you should still be concise and direct.

• Use active voice instead of passive voice
• Strip out business context meant for human engineers
• Avoid flowery language, keep the writing action-oriented

Overly verbose description can result in a higher likelihood of Tusk “overthinking” tasks. The agent could weigh certain words in your extra description more heavily than it should.

​

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, untrimmed 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 and what part of the image is relevant, 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.