A 15-min walkthrough of Hivel, by its Founder
{% embed url="Integrations Guide Integrations page on Hivel
*** ### **Let the Data Flow** Once integrations are set, Hivel starts pulling in your data. Depending on the size of your projects, it may take a little while. You don’t need to wait around - we’ll let you know when it’s ready. *** ### **Shape Your Teams** Now’s the time to set up teams and add users. Organizing things the way your company works makes the insights that follow much more meaningful. In case teams have already been set up, you can go through your teams to get an idea of whether everyone is considered and it is set up properly. {% content-ref url="/pages/Kcsm112Y5JMf7EnIR1df" %} [Team & User Management FAQs](/faqs/team-and-user-management-faqs) {% endcontent-ref %} *** ### **Double-Check Your Data** Trust in your data matters. Take a moment to cross-check Hivel’s numbers with what you see in your SCM and PM tool for starters. This quick validation helps you feel confident in the insights you’re looking at.How to validate the data on Hivel
*** ### **Understand Your Metrics** This is the fun part - you’ll start seeing dashboards that show how your teams and developers are working. Don’t worry if it feels new; just spend a little time getting familiar with the view.Read about the Cockpit Check out Cockpit on Hivel
(where you will find most of the metrics)
Read about the configurations here Configurations page on Hivel
*** ### **Explore Hivel's Main Features** Once you’ve got the basics in place, explore what Hivel has to offer - from goals to detailed dashboards. Here are some functionalities we encourage you to check out first: * Cockpit * Investment * Pull Request Screen * Activity * Download Reports *** ### **Learn Best Practices** We’ve gathered proven ways teams use Hivel to speed up delivery and improve quality. These are small habits that add up to big wins.Steps to take to improve the metrics and performance
*** ### **Set Goals** With your data in place, it’s time to set goals for your teams or the whole org. Goals keep everyone moving in the same direction and help you measure progress over time.Read up on Goals feature and how to set them up New button
*** ### **Make Hivel Part of the Rhythm** The real magic happens when Hivel becomes part of your team’s weekly and monthly check-ins. Look at trends, revisit goals, and celebrate improvements.<space for managers>
*** {% hint style="success" %} ✨ **Tip:** You don’t have to do it all at once. Even if you pause after Step 3 or Step 6, you can always come back here and pick up where you left off. {% endhint %} ***Share Your Thoughts
Your feedback helps us make Hivel better. If you notice something that could be improved or want to see a new feature, let us know. We love hearing from you. # Using Hivel **Welcome to Hivel’s Knowledge Base**\ Your go-to guide for getting the most out of Hivel - from tracking performance and managing goals to optimizing your engineering workflows. Explore how to enhance productivity, streamline collaboration, and make the most of every feature. All your essential Hivel know-how, in one place.| Cockpit | /pages/1yhoXPL29LMS8d5e3Ahf |
| Investment | /pages/j0c0LZvzuIDOTn8cXJ76 |
| Pull Request Screen | /pages/rsPVjRVTJgROOSrOQsGf |
| AI Adoption | /pages/TDwZzXtzymMsjcnRRsrV |
| Goals | /pages/oVRxvlEtUJjGMbxjB7O8 |
| Coding Screen | /pages/QASW5qGBDPGeAQ4Vblt7 |
| Activity | /pages/AJFFHbZKH1BUCM2vx5B4 |
| Dev360 | /pages/XwR5ckkr03SSVzsOf6xb |
| Process Screen | /pages/NBgbKKxL0iPsk3GvHA10 |
| Work Item Breakdown | /pages/UbaoJQLwj2mFxBCnqpAM |
| Coding Hotspots | /pages/Zy3Ah7ZNZ4WfTG7epcBL |
| Hivel Quadrant | /pages/kRO3KJrhTLKp1MVZI3rR |
| Performance Appraisal | /pages/onnfjcjLHbkr5cCZDMpw |
| Lucy | /pages/gmqBgXJ9TBbkspemExfk |
| Hivel Score | /pages/lrOB4mtEkq2mjVH32ZvB |
**Cockpit Pro reports:** Cockpit Pro reports can be downloaded for data in the Speed, Quality, or Throughput buckets. To pull data from all buckets simultaneously, switch to tabular view and select "All." Here’s how to download a Cockpit report: {% embed url="
Accessing from another metric screen
Adding the metric as part of new dashboard creation
You can filter this data based on specific teams and dates to gain the insights you need.
If google calendar is not integrated with Hivel yet, please follow the steps mentioned [here](https://hivel.zendesk.com/hc/en-in/articles/19341040186909-How-to-integrate-Google-Calendar-in-Hivel). If you encounter any issues or have further questions, feel free to contact us at
In Cockpit, the toggle will enable/disable the insights
AI Insights toggle in Configuration screen
Products section
Allocation
Product section
Allocation section
* ***Refactor**:* PRs that need significant changes to improve code quality or structure before they can be merged i.e. comments suggesting extensive changes, restructuring, or optimization of the code. * *For example, "The algorithm here can be optimized for better performance."*
* ***Buggy**:* PRs that introduce new bugs or issues into the codebase i.e. comments highlighting bugs, regressions, or issues that break existing functionality. * *For example, "This change breaks the login functionality."*
* ***Controversial**:* PRs that generate significant debate or disagreement among reviewers i.e. comments that show differing opinions or disputes on the implementation, approach, or necessity of the changes. * *For example, "I don't think this approach is the best solution."* #### **Type 2:** * ***Code Quality**:* Comments focused on the overall design, architecture, and cleanliness of the code i.e. feedback related to code organization, modularity, adherence to design patterns, and overall structural improvements. * *For example, "This module should be broken down into smaller, more manageable components."*
* ***Readability**:* Comments aimed at improving the readability of the code and the adequacy of its documentation i.e. feedback about code clarity, naming conventions, comments within the code, and the presence and quality of documentation. * *For example, "Variable names should be more descriptive."*
* ***Testing**:* Comments that address the sufficiency and quality of tests and error handling mechanisms. Suggestions or concerns regarding unit tests, integration tests, error handling, edge cases, and the robustness of the code against failures. * *For example, "Error handling is not sufficient here; consider adding more checks."*
* ***Compliance**:* Comments that ensure the code adheres to industry standards, coding guidelines, and best practices i.e. feedback on adherence to coding standards, security practices, regulatory compliance, and the use of recommended libraries or frameworks. * *For example, "This code doesn't comply with our security guidelines."*
* ***Maintainability:*** Comments that focus on the long-term maintenance and scalability of the code. Suggestions for making the code easier to maintain, extending its functionality, or improving performance to handle larger scale or more complex operations. * *For example, "This code will be hard to maintain; consider refactoring."* #### **Type 3: Special Cases for Categorization:** * When a comment consists of a single word, it is categorized as a *"**One Word Comment**"*. * If a pull request has no comments, it is categorized as *"**No Comment**"*. * When a pull request cannot be categorized based on its comments due to various reasons, it is categorised as ***"No Value"***. **Wherever applicable, each PR will be categorized into either one or two of the above types. For example -** * "Looks good to me. Well done on keeping the code clean and efficient!" * Categories: ***LGTM, Code Quality*** * “Consider refactoring this function to reduce its complexity and improve readability.” * Categories: ***Refactor, Readability*** * “There's a bug in the validation logic. Please fix it before merging” * Categories: ***Buggy*** * "Looks good to me. Well done on keeping the code clean and efficient!"\ "Can you add more comments to this section for better understanding?" * Categories: ***LGTM, Readability*** * "There's a bug in the validation logic. Please fix it before merging."\ "Make sure to add unit tests to cover this scenario." * Categories: ***Buggy, Testing***
Examples
**You can use data on this screen to:** * See the stage at which your team is spending most of their time - coding, review, or release process. * Averages could sometimes be deceiving, so check the right panel for all the PRs and their respective breakdown into various stages. * You can look at your current sprints or past sprints and use this data during retrospectives. {% hint style="info" %} Refer [here](/using-hivel/pull-request/how-to-exclude-outlier-commits-and-prs) to know how to exclude certain PRs and commits from the calculation. {% endhint %} # Goals ## 🎯 Using Goals in Hivel The **Goals** feature in Hivel helps you set clear targets, track progress, and assess performance at both the **organization** and **team** levels. Whether you're aligning teams around strategic objectives or tracking key performance metrics, Goals provides the visibility and accountability to stay on track.
Maintenance Percentage =
(lines of code modified that were written prior to 30 days) / (total lines of code
added or modified)
Rework Percentage =
(lines of code modified that were written in the last 30 days) / (total lines of
code added or modified)
New Work Percentage =
(lines of code that were written in the specified duration) / (total lines of code
added or modified)
Below are definitions for Bug, Vulnerability, and Code Smell: 1. **Bug** - A coding mistake that can lead to an error or unexpected behavior at runtime. 2. **Vulnerability** - A point in your code that's open to attack. 3. **Code Smell** - A maintainability issue that makes your code confusing and difficult to maintain. Please refer to SonarQube's documentation to know more about the [issue statuses](https://docs.sonarsource.com/sonarqube/latest/user-guide/issues/solution-overview/#life-cycle) and [severities](https://docs.sonarsource.com/sonarqube/latest/user-guide/issues/solution-overview/#life-cycle). # Performance Appraisal The Performance Appraisal screen in Hivel is a powerful tool that allows you to compare the performance of developers or teams using various key metrics. This feature helps you quickly identify where each individual or team stands and if there are any bottlenecks in specific areas.
Org level score calculation | /pages/ZeWHojs64S1TewRU3N2Z |
Team level score calculation | /pages/b35glHGBjWn2P7rS8SpI |
| Cycle Time | /pages/AI4ttvniPZAp0FfQ5H6T |
| Coding Time | /pages/s2ZqKzgFQbPSz2nl8bGS |
| Pickup Time | /pages/HF3iogo5niuFSCn0pvlR |
| Review Time | /pages/9N6yUlhUw05wjOi1Na0z |
| Merge Time | /pages/vILR3RiInp37eEG9vATg |
| Release Merge Freq. | /pages/26gYI5HtX3DxrFBjxHci |
Throughput screen measures volume of work
Active days on Cockpit
Active days on Activity screen
**✅ Acceptance Rate** * **Formula**:
**1. Using Cursor on the the right side of Cursor IDE (Standard Use)** * **How it works**: The developer receives AI suggestions in the code editor, either as suggestions or inline code completions. These suggestions are explicitly accepted by the developer and added directly to the code. * **AI LOC Calculation**: In this case, the **Total AI LOC** is calculated based on the lines added or deleted by the AI suggestions that the developer accepted. Both **Accepted Lines Added** and **Accepted Lines Deleted** are counted in the total AI lines. * **Example**: If the AI suggests adding a new function and the developer click on **Apply** and accepts it, those lines are counted as **AI LOC**.\ \ 
**2. Inline Cursor Usage** * **How it works**: The developer views AI suggestions by selecting a portion of code and click on Quick edit and chat with Agent or GPT odel * **AI LOC Calculation**: In this scenario, **AI LOC is counted**. * **Example**: The developer took quick help for formatting a block of code.\ \  **3. Using Tab Mode (AI LOC not counted)** * **How it works**: The developer uses the AI suggestion directly by click on tab which helps in autocompletion of the code * **AI LOC Calculation**: **AI LOC is not counted** in this case because the developer has not accepted the suggestion as-is. In this case, you get tabs accepted. * **Example**: The developer needs help with autocompletion of code.\  #### 👤 **User Classification** **✅ Active Users** A user is marked as **active** if they: * Received a suggestion. * Edited a file with Cursor open. * Opened Cursor Composer (chat). * Accepted a suggestion. **❌ Inactive Users** A user is marked as **inactive** if no AI interaction occurred on a given day, even if the IDE was open. * **Coverage**: Coverage charts reflect the percentage of active users daily or weekly. **Hivel Calculations for Active/Inactive Users**: * **Active Users** = Number of unique users with **isActive = true** at least once in the selected period. * **Inactive Users** = Total unique users (with any usage record) - Active Users. *** #### 🧱 **Technical Foundations** * **Tracking**: Metrics are tracked on a per-user, per-day basis. * **Reset**: Metrics are reset daily, with historical data available for up to 90 days prior to your integration.
**⚠️ Known Limitations** * **Cursor Suggested Lines Not Accepted**: If the lines suggested by Cursor are shown but not accepted (for instance, when the suggestion is staged but not applied to the code), **the LOC will show as 0**. * **Copy-Pasting**: If a developer copy-pastes content from a suggestion without accepting it via the IDE, it will **not** be counted as AI lines, and the LOC will show as 0. * **Modified Usage**: Any changes made to the code that were inspired by AI suggestions but not directly accepted (such as rewriting or modifying code based on AI suggestions) will not be tracked or counted. * **Offline Use**: If Cursor is used offline, no data is captured. Any actions performed during offline sessions are not counted in the metrics.
**Summary**: **Cursor's metrics primarily track explicit interactions** with AI suggestions and not actions like copy-pasting or modified usage. This can lead to an **underestimation of AI influence**. *** #### 📦 **Sample Cursor Daily Record** | **Field** | **Value** | | ------------------------------- | -------------- | | **email** |
Area
|Metrics Covered
| | ------------- | -------------------------------------------------------------------------------------------------------------------- | | Adoption | Total Active Users, Total Inactive Users, Total Cost, User Segments (Power / Steady / Opportunistic / Inactive) | | Engagement | Suggestions Acceptance rate by mode (Edit / Write / Multi-Edit), Sessions per user | | Effectiveness | Edit Acceptance Rate, Write Acceptance Rate, Multi-Edit Acceptance Rate, Commits, PRs Opened, LOC Added, LOC Removed | #### Key Metric Definitions **Summary Metrics** 1. Total Active Users * Lines of code written using AI for the selected duration. * Displayed: Headline KPI card on the Overview tab. 2. Total Inactive Users * Users with no lines of code generated using AI the selected period. * Displayed: Headline KPI card on the Overview tab.Segment
|Percentile Rule
|Tooltip Definition
| | --------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------ | | **Power Users** | Percentile ≥75% (top 25 percentile by token usage) | Top 25% of users by Claude token usage. | | **Steady Users** | 50th–75th percentile token usage | Regular Claude usage, within the 50–75th percentile. | | **Opportunistic Users** | <50th percentile, >0 tokens | Occasional Claude usage, below the 50th percentile. | | **Inactive Users** | 0 tokens in selected period | User who has licence but has no Claude usage during the selected period. |Tag
|Definition
| | ----------------------------- | ---------------------------------------------------------------------------- | | **New User** | First Claude session occurred within the selected time range. | | **High Delivery** | Users who are part of the top 25% by commits and pull requests created. | | **Usage > Output** | High Claude activity compared to peers, with lower relative delivery output. | Clicking a tag button at the top-right of the table filters the entire list to show only users matching that cohort. Multiple filters can be combined. 🧱 Technical Foundations * Freshness: Metrics reflect activity up to the previous calendar day (T-3 lag). Data is finalised at the end of each UTC day. * Retention: Historical data is available for the period configured in your Hivel workspace (default: 30 days). This guide provides a complete reference for all metrics in the Claude Adoption dashboard. Use it alongside the dashboard to diagnose adoption patterns and build data-driven enablement strategies. # Claude Console Analytics The Claude Adoption feature in Hivel provides valuable insights into how your engineering teams are using Anthropic’s Claude Console. It tracks who is using Claude, how effectively they engage with its suggestions, and how that usage maps to real code delivery - helping you measure ROI and drive adoption across your organization. Data shown includes only billed users and reflects activity/data until the previous day. #### Summary Metrics Three headline KPIs are displayed at the top of the Overview tab, giving an at-a-glance view of Claude engagement for the selected filters and date range: |Total Active Users
71
Users with at least 1 token used
|Total Inactive Users
23
Users with zero token usage
|Total Cost
$12,699.5
Sum of AI-generated cost (Claude Code)
| | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | #### Users Breakdown| Why this matters |
|---|
| Together, these metrics give you a complete picture of Claude’s impact - from who is genuinely engaged and how they are classified, to whether suggestions are trusted, to whether that trust is translating into real code delivery and at what cost. Use this data to make informed decisions about where to drive deeper adoption, where to provide additional training, and whether your Claude investment is delivering the productivity gains you expect. |
Developer distribution across categories and split of Human vs AI generated code
Developer distribution trend
| More about Code Telemetry | /pages/8l1IV2qM1p1LERBAcLc0 |
In summary
* Code Telemetry is a **directional signal**, not a factual claim * It works on **shipped code**, not IDE activity * Confidence scores add transparency, not certainty * It is best used to understand trends over time * Its real value comes from pairing it with delivery metrics With the right expectations, Code Telemetry helps teams reason clearly about AI adoption without overclaiming accuracy or intent. # Best Practices Unlock the full potential of Hivel’s integrations by following these best practices. This guide is designed to help you streamline your workflows, boost team collaboration, and achieve consistent, impactful results. Whether you're optimizing for efficiency, minimizing errors, or ensuring smooth coordination across tools, these best practices will set your team up for success. Dive in to discover strategies that elevate both your integration experience and your overall productivity. *** {% content-ref url="/pages/2c4Ub6CCMTJyaw6zYcAT" %} [Best Practices for Software Development Efficiency](/best-practices/best-practices-for-software-development-efficiency) {% endcontent-ref %} {% content-ref url="/pages/GS2QBXfEZTCTgEK8rIf6" %} [Jira Best Practices](/best-practices/jira-best-practices) {% endcontent-ref %} {% content-ref url="/pages/ICxYHWezFtP5FsbyBsgD" %} [Best practices for AI usage](/best-practices/best-practices-for-ai-usage) {% endcontent-ref %} {% content-ref url="/pages/RkYFJnSkO5SfzUoevCby" %} [AI usage - PR checklist + Prompt Cookbook + Cursor Rules](/best-practices/ai-usage-pr-checklist-+-prompt-cookbook-+-cursor-rules) {% endcontent-ref %} # Best Practices for Software Development Efficiency Streamlining your software development process isn't just about writing code; it's about creating a cohesive, efficient workflow. By adhering to these best practices, you'll not only enhance code quality and team collaboration but also achieve the most insightful visualizations on Hivel, ensuring your projects stay on track and transparent.1. **Keep it Bite-Sized:** Aim for code chunks under 400 lines. Smaller segments are your friends—they're easier to digest, test, and keep bug-free. Few companies go as low as 80 lines per PR. 2. **Kick Off with Commits**: Create a separate branch for each feature development task. As soon as you have a logical conclusion, do a commit - commit early and often. Avoid bundling all changes into a single, large pull request at the end of development. 3. **Peer-Reviews:** Implement a review branch configuration to ensure all PRs are reviewed by someone other than the author before merging. This process helps catch errors, improve code quality, and maintain consistency. Dedicate focused time to PR reviews, especially for larger changes, as thorough reviews are crucial for preventing production bugs and reducing technical debt. Aim for 100% PR review coverage, prioritizing quality over speed to maintain high code standards. 4. **Quality Over Speed:** When reviewing PRs, take your time, especially with the larger ones. A thorough review today saves a headache (and a bug) tomorrow. Avoid flashy reviews (reviewing large chunks of code in few minutes). 5. **Track and Plan:** Always use story points, assignees, and epics in your Jira tickets. It's not just paperwork; it's about making your work visible and planning effectively. No story points for tickets means reduced velocity for work being done, which is like getting no credit for your hard work. 6. **Connect the dots:** Include the Jira ticket ID in your commits and Pull Requests. It creates a clear trail linking your code changes to specific tasks, making it easier to understand the context and purpose of modifications. This practice ensures all your work is properly documented and accounted for, enhancing traceability and project management. 7. **Merge over Squash**: Use merge commits when integrating changes to maintain a clear history, preserving the context of individual modifications and making it easier to track the evolution of features over time. 8. **Embrace Testing:** Write tests for your code, including unit, integration, and end-to-end tests. Testing ensures your code does what it's supposed to do and helps catch issues early. While it may sound like slowing down, it actually will speed up the overall process. 9. **Keep It Clean:** When building new features, refactor surrounding code to improve readability and maintainability. Pay special attention to areas or repositories experiencing frequent rework, as these are prime candidates for refactoring. Regular refactoring keeps your codebase clean, reduces technical debt, and makes development more efficient in the long run. 10. **Document Wisely:** Write clear, concise documentation for your code and features. Good documentation helps others understand your work and saves time when revisiting old code. 11. **Engage in Dialogue:** Leaving comments on the PR is a good practice that encourages open discussion, provides clarity on decisions made, and creates a record of the thought process behind the code changes. 12. **Tag that hotfix!** Implement a systematic approach to differentiate hotfix PRs from regular ones. We suggest using 'hotfix'-related keywords in branch names or adding specific labels to hotfix PRs for easy identification later on. 13. **Sprint Ready: Plan, Tag, and Launch!** Before kicking off any sprint, aim to plan and tag most work to sprints. This gives developers clear visibility into upcoming tasks, allowing them to hit the ground running when the sprint starts. 14. **Distinguish production vs. non-production bugs:** Establish a way to distinguish between production issues and in-sprint issues to improve prioritization and resolution. Common approaches include using a field to tag whether an issue is a production or in-sprint issue, or using separate issue types for each. # Jira Best Practices ## Jira Board Hygiene and Sprint Best Practices Maintaining clean and well-structured Jira boards is essential for reliable sprint planning, predictable delivery, and trustworthy reporting. The practices below are designed to minimize manual effort while maximizing clarity for both developers and leaders. *** ### 1. Before the Sprint Starts #### Create Tickets Ahead of Sprint Start All work intended for a sprint should already exist in the backlog before sprint planning begins. * Create tickets in the backlog and move them into the sprint only after discussion. * Break down large pieces of work into small, actionable tickets that can be completed within a sprint. * Avoid creating tickets directly inside an active sprint unless they are truly unplanned. Why this matters\ Pre-created tickets allow planning to focus on sequencing and tradeoffs rather than discovery under time pressure. *** #### Assign Story Points During Planning Every ticket entering the sprint should have story points assigned. * Estimation should consider complexity, scope, and uncertainty, not individual developer speed. * Points should be agreed upon collaboratively during sprint planning. * Unestimated tickets should not be pulled into the sprint. Why this matters\ Consistent estimation improves velocity tracking and makes future sprint planning more predictable. *** #### Link All Tickets to Epics Every ticket should be associated with an Epic. * Epics represent higher-level goals, initiatives, or customer outcomes. * Epic linkage enables roll-up reporting and clearer progress tracking. * Avoid orphan tickets without an Epic unless explicitly intentional. Why this matters\ Epics create structure and prevent Jira boards from becoming flat task lists with no strategic context. *** #### Assign Ownership Clearly Each ticket should have a single, clear assignee. * Avoid assigning multiple people to one ticket. * Avoid generic or unassigned tickets entering the sprint. * If multiple people are involved, split the work into multiple tickets. Why this matters\ Clear ownership improves accountability and prevents work from silently stalling. *** #### Confirm Team Commitment Before Starting the Sprint Before clicking **Start Sprint**, confirm that: * All tickets have story points. * All tickets are linked to Epics. * All tickets have assignees. * Developers agree the scope is realistic. Summary\ A sprint should only be started once the board reflects committed, estimated, and owned work. *** ### 2. Once the Sprint Is in Progress #### Limit Ad Hoc Work Unplanned work should be the exception, not the norm. * Only add mid-sprint tickets for urgent issues, incidents, or blockers. * Ensure any new ticket added mid-sprint has story points and an Epic. * Discuss the tradeoff openly in standups. Why this matters\ Frequent ad hoc additions erode sprint predictability and distort velocity. *** #### Actively Manage Scope If new work must be added: * Remove or de-scope equivalent work where possible. * Avoid silently increasing total sprint scope. * Make scope changes visible to the team. Why this matters\ Stable scope preserves trust in sprint commitments and delivery metrics. *** #### Adjust Story Points When Reality Changes If a ticket proves significantly larger or smaller than expected: * Update story points to reflect actual effort. * Use this as learning for future estimation. * Avoid retroactively changing points only to “make numbers look good”. Why this matters\ Accurate data matters more than perfect optics. *** ### 3. Before Closing the Sprint #### Ensure Completed Tickets Are in Done Before closing the sprint: * Confirm all finished work is transitioned to the Done status. * Ensure Done reflects your team’s actual definition of done, including testing and review if applicable. Why this matters\ Sprint reports and velocity calculations depend entirely on correct status transitions. *** #### Do Not Carry Done Tickets Forward Once a ticket is marked Done: * Do not move it to the next sprint. * If follow-up work is needed, create a new ticket instead. Why this matters\ Moving Done tickets forward corrupts historical sprint data and reporting. *** #### Handle Incomplete Work Cleanly For tickets that are not finished: * Move them to the next sprint only if work remains. * Re-estimate if scope has changed. * Avoid leaving stale tickets partially done across multiple sprints. Summary\ Only unfinished work should roll forward. Completed work should stay completed. *** ### 4. Low-Effort Jira Automations and Smart Defaults This section focuses on improvements that require **minimal ongoing maintenance** but significantly improve hygiene. #### Automatically Enforce Required Fields Use Jira Automation to prevent bad data from entering sprints. Examples: * Block sprint start if tickets are missing story points. * Auto-comment or flag tickets without Epics. * Warn when tickets are unassigned. Why this matters\ Automation removes the need for manual policing during planning. *** #### Auto-Update Fields on Status Changes Common lightweight automations include: * Set resolution when a ticket moves to Done. * Auto-assign the reporter or component owner when a ticket is created. * Clear assignee when a ticket is moved back to To Do. Why this matters\ This keeps data consistent without adding process overhead. *** #### Tag and Track Unplanned Work Automatically Create an automation rule that: * Labels tickets added after sprint start as unplanned. * Adds them to a dedicated Epic or category. * Optionally posts a comment explaining they were added mid-sprint. Why this matters\ This preserves sprint integrity while still allowing urgent work. *** #### Use Board and Workflow Guards Instead of Manual Checks Prefer system-enforced rules over reminders. Examples: * Workflow conditions that prevent Done without required fields. * Board filters that hide invalid tickets from sprint views. * Quick filters for unestimated or unassigned tickets. Why this matters\ Good defaults reduce reliance on individual discipline. *** ### Benefits of Following These Practices * Clear visibility into sprint progress and risks. * More predictable sprint planning and delivery. * Stronger ownership and accountability. * Cleaner historical data for velocity and trend analysis. * Less time spent fixing Jira instead of shipping software. *** ### Final Summary Clean Jira boards are not about process overhead. They are about creating a shared, reliable system that reflects reality. When tickets are well-defined before the sprint, scope is managed transparently during execution, and automation handles the repetitive checks, teams gain confidence in their delivery and leaders gain confidence in the data. # Hotfix & Jira Integration - Best Practices To ensure high-quality insights into engineering health, we rely on clean and consistent metadata across Git and Jira. This document outlines best practices for accurately identifying hotfixes and enabling accurate metrics, such as Hotfix Resolution Rate and Hotfix Rate. Following these practices will ensure your team’s work is properly tracked and reflected in engineering reports. ### 1. Identify Hotfixes via Pull Request Patterns We detect hotfix PRs by scanning Git metadata for specific keywords across several fields. This is the primary method for classifying a PR as a hotfix. #### Recommended Keywords (These can be configured based on your naming convention) : * hotfix * hot fix #### Fields Scanned: * Label * Title * Description * Branch Name * Tag #### 🔍 Examples: * ***hotfix/fix-auth-bug*** (branch) * ```
What story points are (and what they are not)
Before jumping into best practices, some important things to note: * Story points measure **relative effort, complexity, risk, and uncertainty**, not just time. * Over time, your team will build a velocity (story points completed per sprint) which helps you plan how much work to pull into future sprints. * Capacity is how much your team *can* handle in a sprint, considering availability, meetings, maintenance/support overhead, etc. Story points + velocity allow you to map what your capacity looks like. Story Points embrace the idea of true Agile where teams accept that they must iterate quickly and adapt to unforeseen circumstances. It is important to remember that story points should never be rigidly linked to specific time values. They are and should always remain an estimate of **how large a task is and how risky it might be** - capturing complexity, uncertainty, and effort in a relative sense. 👉 That said, if at any point you notice that following strict story point hygiene is creating friction, feels complicated, or is not truly benefitting your team in representing effort, don’t hesitate to revert back to basics. In our journey, we have seen customers move fluidly between different approaches: from story points to time-based estimates, switching to T-shirt sizing, adopting Kanban tracking even while running internal sprints, or even dropping Jira entirely in favor of good old spreadsheets. The lesson here: **try not to force teams to use story points where they may not make sense.** Often the simplest and most effective practice is to break work down into deliverables small enough (1-3 days in size) that detailed estimation becomes unnecessary.| Practice | Recommendation | Why it helps |
|---|---|---|
| Use a non-linear scale (e.g. Fibonacci or modified Fibonacci) | Use a sequence like 1, 2, 3, 5, 8, 13, 20 etc. You can cap or modify the higher numbers for your context. | Non-linear increases acknowledge that as stories grow in size, uncertainty/risk tends to increase. It makes distinguishing large vs medium tasks more meaningful. |
| Establish a baseline “reference story” | Pick a simple story (e.g. bug fix or small feature) that everyone agrees is “1 point.” Use that as anchor/reference. Compare all other stories relative to that. | Helps calibrate what “1 point” actually means for your team. Without this, one person’s “3” may be another person’s “1”, making planning unreliable. This is widely recommended in agile estimation literature. |
| Use velocity (average over past 3-5 sprints) to determine capacity | Don’t guess how many points you’ll do; use past performance (velocity) to decide how much to commit. Adjust for holidays, support work, known overhead. | It gives realistic limits; teams that do this avoid over-committing and burnout. |
| Factor in non-development/overhead work | Include time for meetings, code reviews, production support, maintenance, etc. That reduces your usable capacity. For example, if someone is allocated 30% support work, the rest should be for new stories. | Without including these, estimates tend to assume 100% dev time, leading to overcommitment. Scrum / Agile coaches often mention treating these as explicit "non-story" work in sprint planning. |
| Limit story size; split large stories | If a story seems too big (e.g. takes more than half a sprint), break it down. Ensure most stories can be completed in a small number of days (1-3). | Smaller stories are easier to estimate, reduce risk, reduce rollback. |
| Use Planning Poker or group estimation | Multiple team members estimate, discuss discrepancies, converge on a consensus. Helps uncover risks / unknowns. | This is a standard practice: helps with shared understanding, surfacing hidden complexity. |
| Don’t map story points directly to hours (or at least don’t rigidly enforce it) | While some teams map approximate hours to small point values for planning (e.g. “1 story point ~ 2 hours”), these mappings should be loose and revisited. | Strict time mapping defeats some of the purpose of story points (dealing with uncertainty). Many sources caution that hour-based equals can be misleading. |
| Use sprints as feedback loops | After each sprint, compare estimated vs actual performance. Review stories that took much longer than estimated to see what went wrong. Use those lessons to recalibrate future estimates. | Improves estimation accuracy over time; reduces mismatch of expectations. |
| Don’t use points to measure individual performance | Measure team delivery: the team’s velocity and capacity vs commitments. Avoid attributing individual productivity to story points. | If individuals are held to “X points per sprint,” it leads to gaming, splitting stories, inflating estimates. Several agile discussions and forums warn against this. |
| Adjust for new teams / changing context | New teams may not have reliable velocity. Projects with new domain or unknown tech will have extra uncertainty. Adjust your expectations (lower velocity, buffer) until data builds up. | Helps avoid overcommitment early and burn-out. Also ensures planning doesn’t assume “steady state” when many variables are uncertain. |
One Pager Sprint Hygiene Checklist
### Before Starting Every Sprint ☐ All tickets in the sprint have story points\ ☐ All tickets are linked to an Epic\ ☐ All tickets have a single assignee\ ☐ Sprint scope has team agreement before clicking Start Sprint *** ### During the Sprint ☐ Avoid adding new tickets unless work is urgent or blocking\ ☐ Any ticket added mid-sprint is clearly marked as unplanned\ ☐ If new work is added, discuss scope tradeoffs in standups\ ☐ Update story points only if scope or complexity truly changes *** ### Before Moving Tickets to Done ☐ Work fully meets the team’s Definition of Done\ ☐ No open subtasks remain\ ☐ Required fields such as resolution are set\ ☐ Done reflects real completion, not just code finished *** ### Before Closing the Sprint ☐ All completed tickets are in Done\ ☐ Incomplete tickets are moved to the next sprint and re-estimated if needed\ ☐ Done tickets are not carried forward\ ☐ Sprint is closed on time without extending dates *** ### Recommended Low-Effort Automations ☐ Flag tickets added after sprint start as unplanned\ ☐ Block Done if required fields or subtasks are incomplete\ ☐ Auto-set resolution when issues move to Done\ ☐ Warn when issues enter a sprint without story points or Epic *** ### Board Visibility Checks ☐ Quick filter for tickets missing story points\ ☐ Quick filter for tickets without Epics\ ☐ Separate visibility for unplanned work\ ☐ Dashboards shared with the team, not just managers *** ### Key Principle to Remember Jira hygiene should be **automatic, visible, and enforced at key moments**.\ If it relies on reminders or manual policing, it will not scale.| Cover image | ||
|---|---|---|
| PR checklist + Prompt Cookbook + Cursor Rules | /files/1LHNcavz1H8tRiElQjmM | /pages/RkYFJnSkO5SfzUoevCby |
| Step | What to do | Why it matters |
|---|---|---|
| Capture Context Before AI Use | In your PR or before prompting AI, clearly define: • The goal (feature/fix/refactor) • The constraints (performance, memory, dependencies, DB schema, API contracts) • Existing patterns/style (coding conventions, error handling, package structure) • What must / must not change (e.g. avoid breaking public APIs) | This ensures the AI’s suggestions are aligned with architecture/style and reduces dangerous drift. |
| Use Good Prompts / Rules | Use structured prompts: • State the goal • Supply relevant context (file snippet, types/interfaces) • Ask for test coverage/error handling/security as needed (see Prompt Cookbook below) • Limit the scope (one file, or one small change) | Better prompt → higher quality suggestions. Helps make suggestions easier to review. |
| Review AI Suggestions Like Code Reviews | When you see AI generated or assisted code: • Read it line-by-line • Check correctness, edge cases, security, resource use, database effects • Ensure readability, maintainability, naming & consistency with team style • If using Copilot: experiment with alternative suggestions; pick the best one. | Prevents introducing bugs or messy code. Ensures AI is augmenting, not replacing human oversight. |
| Tests, Error & Boundary Cases | Always ensure: • Unit tests / integration tests cover new or changed logic, especially for edge cases • Error handling, failure modes are considered (invalid input, timeouts, nulls etc.) • Database transactions are safe, schema compatibility maintained. | Many AI outputs fail at boundary conditions. Testing ensures code works as expected. |
| Security / Sensitive Data Review | • Don’t paste secrets or credentials into prompts or code. • Use static analysis / code scanning for security vulnerabilities. • Review for injection risks, permission leaks, untrusted inputs. • Keep modules that access sensitive data under tighter human review. | AI may suggest insecure patterns. Avoid accidental data exposure. |
| Fit With Existing Architecture & Dependencies | • Make sure suggested code plays nicely with existing services, modules, patterns. • Avoid duplicating functionality, violating modular boundaries. • Upkeep dependency versions and compatibility. | Keeps maintainability high and avoids technical debt. |
| Document Changes & Rationale | If you accept an AI suggestion that changes logic/design: • Write in PR description what was changed, why. • Indicate what trade-offs were made. • If AI used rules / patterns, reference them. | Helps reviewers understand why AI was used; aids future maintenance. |
| Code Review Signoff & Ownership | • Even if AI wrote a lot, a human must own the change. • Reviewers should verify code quality, tests, performance. • Do not use “AI did it” as justification for skipping review. | Accountability + high quality. |
| Monitor Post-Merge Behavior | After merging: • Track fallout: bugs, regressions, customer issues. • If this change increases errors / rejects during QA, revisit the usage. • Retrospect what worked / what didn’t. | Data ensures learning and iteration; metrics reflect reality. |
| Continuous Improvement | • Periodically share best prompt examples internally. • For Cursor - Update rules or style guide based on what suggestions are bad / common failures. • Run occasional audits of AI-assisted PRs to see where suggestions consistently fail. • Collect peer feedback. | Helps reduce noise, improve quality over time. |
| Task | Prompt Template | Notes / Things to Include |
|---|---|---|
| Feature Implementation | “Implement a <feature> in <component / service> that does <behavior>. Use <libraries> if relevant. Write unit tests as well. Ensure error handling for invalid inputs, timeouts, and DB failures. Match existing coding style.” | Include the goal, the component or module name, test requirements, error / edge conditions, match style. |
| Refactor / Clean Up | “Refactor method <methodName> in <file> to simplify logic. Preserve existing behavior and API contract. Add tests if coverage is low. Ensure naming and error handling follow team conventions.” | Helps preserve correct functionality. Trigger deeper thinking. |
| Bug Fix | “Fix bug where <describe bug> in <module> (e.g. “when user submits empty field, backend 500s”). Include tests reproducing bug and fix. Also review for similar occurrences elsewhere.” | Including description and reproducibility helps. Asking to scan for similar patterns improves code hygiene. |
| Performance / Optimization | “Optimize the query in <module> retrieving <data> from Postgres. Consider indexes, limit/pagination, avoid N+1, use appropriate joins. Retain readability and maintainability. Show before/after rationale.” | Encourages thinking about performance tradeoffs. |
| Security / Sanitization | “Add input validation, sanitization, and secure practices for <endpoint / service> that takes user input. Ensure prevention of SQL injection, XSS, unauthorized access. Write tests for invalid inputs.” | Promotes safer code. |
| Code Review Helper | “Review this diff / file: <paste snippet>; point out issues for readability, maintainability, test coverage, security, style mismatches. Suggest small fixes or improvements.” | Useful to catch oversights before PR. |
| Writing Tests | “Write unit tests(s) for <component / service> that cover success cases, invalid inputs, error paths. Use <test framework>.” | Ensures test coverage. |
| Database Schema Changes / Migrations | “Suggest a migration to introduce <new column / table> while preserving existing data. Write migration script. Update service layer and repository accordingly. Ensure backward compatibility.” | Important for DB-safe evolution. |
| Branch Configurations | /pages/nn79xjnPy7ieOYMCVwm9 |
| General Configurations | /pages/PoMWFRYZukuvshdpccZq |
| Hotfix Configurations | /pages/0I8PaH5G1taYNbjBph1b |
| Metric Behaviour | /pages/5mI95x6KAxhQ9klXXtIC |
| Exclusions | /pages/fux6PrD4udyDNqb49shC |
| Investment Configurations | /pages/RvM3KWUFMesxJ5p6cwem |