AI optimization insights

How Latchkey generates workflow optimization recommendations automatically, and how to apply them as pull requests.

Latchkey's AI continuously analyzes your monitored workflows and produces concrete, per-workflow recommendations: caching improvements, redundant steps, runner right-sizing, reliability fixes, and more. You review them on the Optimization Insights page and apply the ones you want as a pull request.

The lifecycle#

The important property of this lifecycle: nothing changes in your repositories until you decide it should. The AI proposes; every change ships as an ordinary pull request that you review and merge yourself.

When recommendations are generated#

Generation is automatic and event-driven; there is no button to press. The agent runs:

• After the initial backfill of a newly monitored repository.
• When a workflow file changes on the analysis branch.
• When a workflow hits repeated consecutive failures, which also triggers a diagnostic analysis.
• On a cost spike (a run costing far above the recent average).
• On performance degradation (a run taking far longer than the recent average).

A processing banner shows on the page while an analysis is running. New recommendations also trigger a notification if you have that type enabled.

The five recommendation categories#

Each recommendation is specific, like "add npm caching to the build job" or "pin GitHub Actions to commit SHAs". Some examples of what each category produces:

Reading the page#

• Optimization Overview: a health badge with priority counts (High, Medium, Low), the distribution of recommendation types, and estimated monthly savings.
• Top Optimization Opportunities by repository and by workflow.
• Insight Severity Distribution and Insight Resolution Rate.
• AI Optimization Insights table: recommendations grouped by workflow, each with a confidence score.
• Trends: insights generated over time and confidence score trends.

Working with confidence scores#

Every recommendation carries a 0-100% confidence score, shown as a segmented gauge and a color-coded badge: High at 80%+ confidence, Medium at 50%+, Low below 50%. A practical way to treat it: the score sets how much of your own review effort a recommendation deserves, not whether it is worth reading at all.

Beyond the score, each recommendation ships with a detailed description, implementation steps, supporting evidence, and known risks. Cost and performance recommendations add a Current State vs Optimized State comparison covering Duration, Cost/run, Success rate, and Runner, plus a Potential Savings figure: dollars per month, time saved per run, and percent faster. You know what merging a change is worth before you act.

One lever you control here: the agent analyzes with your Knowledge Base as context, so uploading runbooks and conventions gives it more of the ground truth an engineer would want before proposing a change.

Inside the review drawer#

Click View Insights on a workflow to open the full-screen review drawer. It has two tabs: a per-card review and a final file preview. The per-card view walks you through each recommendation in three sections:

• Best Practice Insights: advice that cannot be expressed as an automatic YAML edit. Mark each item "I've done this" or "Not relevant".
• Code Change Insights: each change renders as an inline diff block, removed lines in red, added lines in green. Choose "Apply with Latchkey" or "Skip this" per change. Linked changes that must ship together carry a Group badge; accepting one accepts the whole group.
• Changes Requiring Manual Placement: if the workflow file changed after analysis, a change that can no longer be placed automatically is flagged here. Choose "I'll apply this" and handle it by hand.

The AI Insights Breakdown panel on the right shows full detail for the selected recommendation, with previous and next navigation, the state comparison, savings, and the confidence gauge. The drawer header keeps a running tally of Available, Accepted, and Declined recommendations, and the footer offers Cancel, Select All, and Apply.

The Final file preview tab renders the exact proposed file with only your accepted changes, so you see precisely what will land in your repository. The net effect: you review AI changes the way you review a teammate's PR, line by line, with full context.

Applying recommendations as a PR#

A useful drawer habit#

You do not have to apply everything a drawer offers in one go. A suggested rhythm: select the high-confidence recommendations first and ship them as one small, easy-to-review PR, then come back for the lower-confidence items individually. Small PRs get reviewed and merged; a single PR that rewrites half a workflow tends to sit.

When that happens, the listed items are not lost work: the PR that was opened is yours to edit, so you can place those remaining changes by hand on the same branch, using the recommendation's description of what it changes and why as your guide.

How recommendations resolve#

The insights list stays current on its own. A recommendation resolves when:

• You apply it through the PR flow and merge the change.
• Latchkey detects you fixed the issue manually.
• The workflow changes so the advice no longer applies; stale recommendations are auto-resolved so they stop resurfacing.
• A recurring failure stops recurring (for diagnostic insights).

The result is a list you can trust: open items are real, and you never wade through advice for problems you already solved.

Failure diagnosis#

When a pipeline fails, a diagnostic agent starts automatically: nothing to configure, nothing to trigger by hand. It reads the failed job logs, compares the failing workflow file against the last passing run on the same branch, and pinpoints the exact error location. The result lands on this page as a Diagnostic insight that answers three questions: what broke, why it broke, and what to do about it.

Each diagnosis classifies the failure as one of nine types: build error, test failure, dependency issue, environment error, timeout, resource limit, configuration error, external service, or flaky test. It flags whether the failure is recurring or a one-off, and like every recommendation, it carries a confidence badge.

While the analysis runs, a live banner at the top of the page shows what is happening: a headline such as "Diagnostic agent is investigating a pipeline failure", a stage label such as "Finding root cause" or "Generating recommendations", and a progress bar. When the diagnosis is ready, you are notified with the root-cause summary and the number of suggested fixes.

Where the fix can be expressed as a workflow YAML change, you get an applyable change you review in the same drawer as every other recommendation, diff in front of you. Where it needs a human, you get manual steps instead, clearly separated so nothing is silently mis-applied.

Diagnosis and self-healing#

The two are complementary, not redundant: self-healing rescues the run in progress, and diagnosis makes sure the same failure does not keep happening.

FAQ#