Guide · Agent skill
How to use the Measure Before You Fix agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Measure Before You Fix is an agent skill for gbrain users. When an alert says a step is slow, stale, timed out or stuck, it tells the agent to time that step on the specific item named in the alert before changing any timeout, threshold or pipeline. This guide covers what the skill does, how to install it, how to trigger it with ordinary requests, and what it needs. You will also see how it separates 'needs more time' from 'is wedged'.
Measure Before You Fixgarrytan/gbrain · MIT Download the skill Quick start
- 1Download the skill ZIP. Get the ZIP for measure-before-you-fix from this page.
- 2Install it. Unzip into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Make a plain request. Describe the alert, for example 'the sync keeps timing out'. The skill is triggered by phrases like this.
- 4Time the named step. Run time gbrain sync --source source-a --no-embed on the specific source the alert names.
- 5Check sync lag and timeouts. Run gbrain sources status and grep the wrapper or cron script for timeout settings.
- 6Compare against the authoritative threshold. Check the alert's threshold against gbrain doctor's warn and fail lines before calling the system unhealthy.
- 7Decide the fix from the measurement. Use the verdict to choose between needs more time and is wedged, then make the separate fix.
What does the measure-before-you-fix skill make the agent do?
The skill targets temporal alerts: claims such as 'X is stale', 'step timed out', 'pipeline wedged', 'job is slow' or 'N hours behind'. Those alerts tend to invite an immediate structural fix like raising a timeout, splitting a step or reordering a pipeline. The skill asks the agent to run one stopwatch measurement of the suspect step first.
The skill is read-only. It changes no timeouts, thresholds or code. Its output is a measurement verdict that sizes the fix, and the actual fix is a separate change made afterwards.
- Reads the alert's own numbers and notes where they contradict the theory.
- Times the suspect step on the specific named entity, not the aggregate.
- Compares the measured time against the alert's configured threshold and against gbrain doctor's warn and fail lines.
- Labels the verdict as either 'needs more time' or 'is wedged', since those need opposite fixes.
How do you install the Measure Before You Fix skill?
Download the ZIP for the skill from this page. Unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it to apply only to that project.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/.
- Project install: unzip into the project's .claude/skills/ folder.
- Claude apps: Settings → Capabilities → Skills, then upload.
How do you trigger the skill with natural requests?
You do not need a special command. Describe the alert in plain words and the agent should pick up the skill. The skill's trigger phrases include 'keeps timing out', 'ETIMEDOUT', 'why is this data stale', 'freshness alert', 'wedged', 'job is slow', 'sync is stuck' and 'raise the timeout'.
Asking for a timeout increase is a useful test. The skill is designed to make the agent measure before it raises one.
- 'Our sync keeps timing out, can you raise the timeout?'
- 'Why is this data stale? The freshness alert fired again.'
- 'The source-a sync seems stuck. Is it wedged?'
How does the measurement walkthrough work?
Start by reading the alert's own numbers. Then time the smallest unit the alert blames, on the specific entity it names. Running the whole brain hides which member is slow, so use a source flag. Check per-source sync lag with the sources command.
Next, find every timeout in the wrapper or cron script, not just the default in the helper. A generous override at the call site makes the default irrelevant. Last, compare the alert threshold with the one gbrain doctor uses before you call the system unhealthy.
- Read the alert output first. For example, 'Locks: none' means lock contention is not the cause, so that branch can be dropped.
- Time the step on one named source.
- Grep the wrapper for timeout settings.
- Confirm the alerter and gbrain doctor agree on what counts as bad.
- Design a fix only against the number you measured.
time gbrain sync --source source-a --no-embed
gbrain sources status
grep -n "timeoutMs\|timeout:" <the wrapper or cron script>How do you check thresholds against gbrain doctor?
gbrain doctor's sync-freshness check defaults to 24 hours for warn and 72 hours for fail. You can override those with the environment variables GBRAIN_SYNC_FRESHNESS_WARN_HOURS and GBRAIN_SYNC_FRESHNESS_FAIL_HOURS.
A cron monitor that acts early is fine. The problem is a monitor that also speaks at its action line, because everything between that line and the doctor's warn line becomes a repeating page about a healthy system. The skill's guidance is to act at the aggressive line and alert at the authoritative one. Record the exact check and threshold before you declare the system unhealthy.
- Symptom to watch for: a repeating alert whose numbers sit below doctor's warn line while the resource looks fine when queried directly.
- Keep the act threshold and the alert threshold as separate constants.
const ACT_HOURS = Number(env.MONITOR_ACT_HOURS || 12);
const ALERT_HOURS = Math.max(ACT_HOURS, DOCTOR_WARN_HOURS);What does the skill need, and is it safe to run?
The skill needs the gbrain CLI with its doctor, sync and sources commands, plus a shell with the time command and grep available. It runs no scripts of its own and makes no network calls, according to the skill's listing.
Because it is read-only, running it does not change your timeouts, thresholds or code. The commands it suggests, such as gbrain sync with a source flag, do run against your gbrain setup, so use the same care you would with any sync command.
- Requires: gbrain CLI (doctor, sync, sources), shell with time and grep.
- Runs scripts: no.
- Uses network: no.
- Licence: MIT.
What mistakes does the skill help you avoid?
The most common mistake is raising a timeout on a step that is genuinely hung. A bigger budget only makes it hang longer. The skill also warns against rewriting a pipeline on a starvation theory nobody has measured, and against trusting an alert's causal claim, since alerts report symptoms more reliably than causes.
The skill also flags red flags such as having a root cause but no measured duration, or revising a theory twice without taking a new measurement in between.
- Raising a timeout to fix a stall.
- Rewriting a pipeline on an unmeasured theory.
- Trusting the alert's stated reason.
- Writing an unmeasured root cause into a playbook.
What people use it for
- Diagnosing a sync that keeps timing out by timing one named source before raising any timeout.
- Investigating a freshness alert that fires below gbrain doctor's warn line and finding the monitor threshold is the cause.
- Checking whether a stalled sync is still making progress or is wedged, before choosing a fix.
- Reviewing a cron monitor's timeout settings to find a per-call override that makes the helper default irrelevant.
Frequently asked questions
How do I install the measure-before-you-fix agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What does the measure-before-you-fix skill require?
It requires the gbrain CLI with its doctor, sync and sources commands, plus a shell with the time command and grep available. The listing says it runs no scripts and uses no network.
Is the measure-before-you-fix skill free?
The skill is listed under the MIT licence. The source does not state a price, so check the page for any terms before you rely on it.
Does the skill fix timeouts or bugs automatically?
No. The skill is read-only and changes no timeouts, thresholds or code. It only produces a measurement verdict, and any fix is a separate change you make afterwards.
Can I use this skill without gbrain?
Not really. Its thresholds and commands are specific to gbrain's tooling, so it does not apply to projects that do not use gbrain.
Why does my freshness alert fire when the sync looks healthy?
The alert may be using a lower act threshold than gbrain doctor's warn line. Compare your monitor's number with the doctor's 24-hour warn and 72-hour fail defaults, or your environment overrides, and align the alert to the authoritative line.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers who run gbrain sync, doctor or cron monitors and keep getting timeout or freshness alerts, and who want a measure-first routine rather than guessed fixes. It is a poor fit for projects that do not use gbrain, or for urgent outages where a known runbook should be followed immediately, since its purpose is to delay structural changes until they are measured.
Download the skill