> For the complete documentation index, see [llms.txt](https://docs.logilica.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.logilica.com/advanced/best-practices.md). # Best Practices This guide maps common engineering challenges to the Logilica dashboards and metrics that help you understand, diagnose, and improve them. ## How to Use This Guide 1. **Identify your challenge** from the sections below 2. **Navigate to the recommended dashboards** to understand the current state 3. **Look at the suggested indicators** to diagnose root causes 4. **Take the recommended actions** to drive improvement 5. **Track progress** over time using the same dashboards *** ## Delivery Speed & Lead Time **Challenge:** Features and tickets take too long from creation to completion. ### Dashboards to Use | Dashboard | What to Look For | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | [Ticket Lead Time](/metrics-and-reports/planning/ticket-lead-time.md) | Stage breakdown — identify whether delays are in Backlog, Pickup, or Resolution | | [Code Cycle Time](/metrics-and-reports/code/code-cycle-time.md) | PR stage breakdown — identify whether delays are in Development, Response, Review, or Integration | | [Ticket Activities / Risks](/metrics-and-reports/planning/ticket-activities-risks.md) | Long Running WIP tickets — items stuck for extended periods | ### Key Indicators * **Long Backlog stage:** Tickets are created but sit unassigned — indicates prioritisation or capacity issues * **Long Pickup stage:** Tickets are assigned but work hasn't started — indicates overloaded assignees or unclear requirements * **Long Resolution stage:** Work has started but isn't completing — indicates large scope, blockers, or context switching * **Long Response stage (PRs):** PRs are open but reviews haven't started — indicates insufficient review capacity ### Recommended Actions * Break down large tickets into smaller, well-specified tasks (smaller tasks have shorter lead times) * Address the specific bottleneck stage rather than applying general pressure * If Pickup is long, check [Ticket Overload](/metrics-and-reports/planning/ticket-overload.md) to see if assignees are juggling too many items * If Response is long on PRs, allocate more review capacity or reduce PR sizes *** ## Throughput & Velocity **Challenge:** The team isn't shipping enough work relative to expectations. ### Dashboards to Use | Dashboard | What to Look For | | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | [Ticket Velocity](/metrics-and-reports/planning/ticket-velocity.md) | Throughput trends, backlog growth rate, ticket size distribution | | [Coding Velocity](/metrics-and-reports/code/coding-velocity.md) | PR merge rate, PR backlog accumulation, work focus (New vs. Rework vs. Maintenance) | | [Sprint Health](/metrics-and-reports/planning/sprint-health.md) | Sprint overrun %, planned vs. unplanned work ratio | ### Key Indicators * **Growing backlog:** Tickets or PRs are accumulating faster than they're being closed — capacity shortfall * **High Maintenance %:** A large share of coding effort goes to maintaining old code rather than new features — signals technical debt * **High Rework Others %:** Developers frequently change each other's recent code — may indicate unclear ownership or poor initial quality * **High unplanned work ratio:** Frequent interruptions displace planned sprint work ### Recommended Actions * Reduce ticket and PR sizes — smaller items have higher throughput * If Maintenance % is high, allocate dedicated time for technical debt reduction * If unplanned work is high, implement stronger sprint boundaries or triage processes * Monitor the investment breakdown over time to ensure effort aligns with organisational priorities *** ## Sprint Planning Accuracy **Challenge:** Sprints consistently overrun or planned work doesn't get completed. ### Dashboards to Use | Dashboard | What to Look For | | ------------------------------------------------------------------- | --------------------------------------------------------- | | [Sprint Health](/metrics-and-reports/planning/sprint-health.md) | Overrun %, unplanned work ratio, investment breakdown | | [Ticket Velocity](/metrics-and-reports/planning/ticket-velocity.md) | Whether ticket sizes are consistent and predictable | | [Ticket Overload](/metrics-and-reports/planning/ticket-overload.md) | Whether team members have too many concurrent assignments | ### Key Indicators * **Sustained high overrun %:** Planning consistently underestimates effort or scope — not a one-off but a pattern * **High unplanned work:** External interruptions are displacing planned items * **Variable ticket sizes:** Inconsistent task sizing makes estimation unreliable ### Recommended Actions * Use historical velocity as a planning input rather than aspirational targets * Standardise ticket sizing (story points or t-shirt sizes) and track estimation accuracy * Ring-fence a portion of sprint capacity for unplanned/interrupt work * Focus on trends across sprints rather than single-sprint anomalies *** ## Team Health & Burnout Risk **Challenge:** Team members are overloaded, context switching too much, or at risk of burnout. ### Dashboards to Use | Dashboard | What to Look For | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | [Ticket Overload](/metrics-and-reports/planning/ticket-overload.md) | % of team with too many concurrent tickets — sustained overload is a red flag | | [Developer Health](/metrics-and-reports/code/developer-health.md) | % of developers with too many concurrent open PRs | | [Team Pulse](/metrics-and-reports/team-management/team-pulse.md) | Per-member load status (Available / Active / Overloaded), WIP counts, blockers | | [Activity Lens](/metrics-and-reports/team-management/activity-lens.md) | What each person is actively working on, how long items have been in progress | ### Key Indicators * **Sustained overload across the team:** Not a temporary spike but a structural issue — too much work for available capacity * **Individual outliers:** Specific team members consistently overloaded while others are available — work distribution issue * **High WIP per person:** People juggling many items leads to context switching and slower delivery on all of them ### Recommended Actions * Redistribute work from overloaded team members to those with available capacity * Reduce overall WIP limits — fewer concurrent items means faster completion of each * Use Team Pulse for regular check-ins rather than as a performance measurement tool * If overload is sustained across the team, escalate as a resourcing issue *** ## Code Quality & Review Process **Challenge:** Code quality issues, review process violations, or too many risky changes shipping without proper review. ### Dashboards to Use | Dashboard | What to Look For | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | [Review Process](/metrics-and-reports/code/review-process.md) | Merge success rate, % merged without approval, process flow bypass rates | | [Code Activities / Risks](/metrics-and-reports/code/code-activities-risks.md) | Risky Changes, Complex Reviews, PRs merged outside process | | [Coding Velocity](/metrics-and-reports/code/coding-velocity.md) | Work focus breakdown — high Rework Others % may indicate quality issues | ### Key Indicators * **PRs merged without review/approval:** Direct process violation — quality risk * **High % of Risky Changes:** Large PRs that are harder to review thoroughly * **High Complex Review count:** Reviews requiring many comments or cycles — may indicate unclear requirements or large scope * **High non-productive work:** PRs opened but abandoned — wasted effort ### Recommended Actions * Enforce review and approval requirements — target 0% merged outside process * Break down large PRs to reduce the number of Risky Changes * Investigate Complex Reviews to understand whether they stem from PR size, unclear requirements, or domain complexity * Track non-productive work to understand why PRs are being abandoned *** ## Build & CI/CD Reliability **Challenge:** Builds are slow, unreliable, or blocking team progress. ### Dashboards to Use | Dashboard | What to Look For | | -------------------------------------- | ---------------------------------------------------------------------------- | | [Build](/metrics-and-reports/build.md) | Build reliability %, average duration, recovery time, per-pipeline breakdown | ### Key Indicators * **Low reliability:** High failure rate means teams are frequently blocked waiting for fixes * **Long build duration:** Slow builds reduce developer productivity and increase cycle time * **Long recovery time:** When builds break, how long until they're fixed — long recovery means extended team blocking ### Recommended Actions * Prioritise improvements where: reliability is low AND many teams depend on the pipeline AND duration is long * Reduce build times to remove productivity blockers * Improve reliability to reduce developer frustration and stalled releases * Track recovery time and establish on-call or ownership for critical pipelines *** ## Epic & Project Delivery **Challenge:** Epics or large initiatives are slipping against target dates. ### Dashboards to Use | Dashboard | What to Look For | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | [Epics Delivery Tracker](/metrics-and-reports/epics-delivery-tracker.md) | Burndown chart, forecast vs. target variance, code activity correlation | ### Key Indicators * **Upward spikes in burndown:** New items being added mid-epic — scope creep * **Forecast date significantly after target:** Velocity-based projection shows a miss * **Low code activity despite many open items:** Work isn't progressing even though tickets exist * **High variance:** Widening gap between forecast and target over time ### Recommended Actions * Track and limit mid-epic scope additions * Use the velocity-based forecast as an early warning signal for stakeholder communication * Investigate disconnect between open items and code activity — items may be blocked, poorly specified, or waiting on dependencies * Adjust scope or timeline early rather than hoping velocity will increase *** ## Cross-Team Visibility **Challenge:** Need to understand how multiple teams are tracking and where to focus management attention. ### Dashboards to Use | Dashboard | What to Look For | | ------------------------------------------------------------------------ | ---------------------------------------------------------- | | [Teams Overview](/metrics-and-reports/team-management/teams-overview.md) | Per-team metrics: cycle time, WIP, work focus, risk counts | ### Key Indicators * **Outlier teams:** Teams with significantly different cycle times, risk counts, or work focus compared to peers * **High risk counts on specific teams:** Accumulated Stale PRs, Long Running WIP, or Risky Changes ### Recommended Actions * Compare teams with caution — different teams have different work types, cadences, and domain complexity * Use outliers as signals for follow-up conversations, not as performance rankings * Drill into specific teams that show anomalies to understand root causes before acting *** ## Metrics Anti-Patterns Engineering metrics are powerful tools for improvement, but they cause harm when misused. Avoid these well-documented anti-patterns: ### Don't Use Metrics for Individual Performance Ranking Metrics like cycle time, PR count, or lines of code should never be used to rank or evaluate individual developers. The most impactful engineers often show lower personal throughput because they spend time unblocking others, mentoring, or doing architectural work that doesn't show up in commit counts. Using metrics for individual ranking encourages gaming (splitting work into trivial PRs, avoiding reviews, cherry-picking easy tickets) and erodes trust. **Use metrics at the team level** to identify systemic issues. Use one-on-one conversations to understand individual contributions. ### Don't Optimise One Metric in Isolation Improving one metric at the expense of others is counterproductive: * Inflating **deployment frequency** with trivial changes doesn't improve delivery capability * Reducing **change failure rate** by deploying less defeats the purpose of tracking delivery performance * Pushing for shorter **cycle times** by skipping reviews trades speed for quality The DORA metrics, work type breakdowns, and risk indicators are designed as a balanced set — interpret them together, not individually. ### Don't Treat Thresholds as Targets When a metric becomes a target, it ceases to be a useful measure (Goodhart's Law). Logilica's thresholds for Risky Changes, overload, and build reliability are signals for investigation, not pass/fail criteria. A team that consistently exceeds a threshold may have a legitimate reason — large PRs in a migration phase, high WIP during a critical launch. **Investigate anomalies before acting on them.** ### Account for AI-Generated Code If your team uses AI coding tools (Copilot, Cursor, Claude Code), be aware that AI-assisted development can distort traditional metrics: * **Deployment frequency** may increase without a proportional increase in meaningful output * **PR sizes** tend to grow with AI assistance, which can inflate "Risky Change" counts * **Review time** may increase as reviewers spend more time validating AI-generated code * **Code quality signals** like rework rate may behave differently for AI-generated code Monitor your [AI Coding](/metrics-and-reports/ai-insights.md) metrics alongside delivery metrics to understand the full picture. *** ## Setting Up Targets & Thresholds Logilica includes [configurable targets and thresholds](/configuration/targets-and-thresholds.md) with industry defaults. When setting your own: * **Start with defaults** and adjust based on your team's context and baseline * **Focus on trends** rather than absolute values — improvement matters more than hitting a specific number * **Review thresholds quarterly** as team maturity and processes evolve * **Use thresholds as conversation starters**, not enforcement mechanisms --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.logilica.com/advanced/best-practices.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.