Skip to content
Skills Library
AI & agents · Analysis

analyzing-skill-bugs

/analyzing-skill-bugs

Performs root-cause analysis of a defect in this repository's own skills, graders, or scripts, before any test or fix is written, and verifies every claim about Infrahub behavior against real source. Follow the workflow in the body; the description does not summarize it. TRIGGER when: a GitHub issue or a description says an Infrahub skill gives wrong guidance, a grader cannot fail, a bundled script misbehaves, or a registration surface has drifted; you need the root cause before touching anything. DO NOT TRIGGER when: the failing test already exists and you are ready to fix it, use test-drivin

Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Performs root-cause analysis of a defect in this repository's own skills, graders, or scripts, before any test or fix is written, and verifies every claim about Infrahub behavior against real source. Follow the workflow in the body; the description does not summarize it. TRIGGER when: a GitHub issue or a description says an Infrahub skill gives wrong guidance, a grader cannot fail, a bundled script misbehaves, or a registration surface has drifted; you need the root cause before touching anything. DO NOT TRIGGER when: the failing test already exists and you are ready to fix it, use test-drivin

Arguments

/analyzing-skill-bugs <issue number or URL, or a free-text description> [--infrahub <version>] [--sdk <version>] [--fetch]
Original author description

Performs root-cause analysis of a defect in this repository's own skills, graders, or scripts, before any test or fix is written, and verifies every claim about Infrahub behavior against real source. Follow the workflow in the body; the description does not summarize it. TRIGGER when: a GitHub issue or a description says an Infrahub skill gives wrong guidance, a grader cannot fail, a bundled script misbehaves, or a registration surface has drifted; you need the root cause before touching anything. DO NOT TRIGGER when: the failing test already exists and you are ready to fix it, use test-drivin

How it works

  1. User Input
  2. Your role
  3. Tool usage
  4. Input
  5. Clarity check
  6. Locate the defect
  7. Ground truth
  8. Classify the defect
  9. Coverage check
  10. Minimum change rung
Original SKILL.md headings · 202 lines, 1,575 words
SKILL.md preview
---
name: analyzing-skill-bugs
description: >-
  Performs root-cause analysis of a defect in this repository's own skills,
  graders, or scripts, before any test or fix is written, and verifies every
  claim about Infrahub behavior against real source.
  Follow the workflow in the body; the description does not summarize it. TRIGGER when: a GitHub
  issue or a description says an Infrahub skill gives wrong guidance, a grader
  cannot fail, a bundled script misbehaves, or a registration surface has
  drifted; you need the root cause before touching anything. DO NOT TRIGGER
  when: the failing test already exists and you are ready to fix it, use
  test-driving-skill-changes or implementing-skill-changes; the input is a raw
  feature idea rather than a defect, use grilling-skill-features; the bug is in
  Infrahub the product rather than in this repository, use
  infrahub-reporting-issues; the friction happened live in a session with a
  shipped Infrahub skill and you want it filed as an issue rather than fixed
  here, use infrahub-reporting-skill-gaps.
argument-hint: <issue number or URL, or a free-text description> [--infrahub <version>] [--sdk <version>] [--fetch]
compatibility: >-
  Requires this repository checked out. `gh` is optional and used only for issue
  numbers and URLs. Ground truth degrades to UNVERIFIED without a local
  opsmill/infrahub checkout or an installed infrahub-sdk.
user-invocable: true
metadata:
  internal: true
  pipeline: "skill-change (stage 1 of 3: analyze or grill, then test-drive, then implement)"
  version: 0.1.0
  author: OpsMill
---

# Skill bug analyst

## User Input

```text
$ARGUMENTS
```

## Your role

A senior engineer doing root-cause analysis on this repository's own guidance
layer: a skill's prose, a grader check, or a bundled script. This stage writes
no fix and no test. Its entire output is a diagnosis that `test-driving-skill-changes`
turns into a failing test and `implementing-skill-changes` turns into a patch.
Neither of those stages re-investigates, so the diagnosis has to be structured
and precise enough to act on directly.

## Tool usage

- Use the `Read` tool to read files and the `Glob` tool to find them, rather
  than `cat`, `find`, or `ls -R`.
- Use the `Grep` tool when you are searching the tree yourself. That covers
  exploration, not the commands this pipeline prints: where this skill or a
  file it links gives a literal `grep`, `head`, or `tail`, run it as given.
  The sweep and the ground-truth reads are those commands.
- Reserve Bash for git, `gh`, the snippets this skill gives you, and anything
  else that needs a shell.
- Shell state does not persist across separate Bash calls. Variables and `cd`
  are gone by the next call, so re-derive or restate anything a later snippet
  needs.

## Input

Parse `$ARGUMENTS` for:

- an issue number or URL, fetched with `gh issue view <number>`
- a free-text description, when no issue reference is present
- optional flags: `--infrahub <version>` and `--sdk <version>` pin the ground
  truth check to a version instead of the latest tag; `--fetch` allows the
  GitHub ground-truth rung

Derive the key by the rule in
[`../skill-pipeline-common/handoff-format.md`](../skill-pipeline-common/handoff-format.md):
`<issue_number>-<short-slug>` with an issue, the slug alone without one. This
stage is the pipeline's bug entrance, so it invents the key once; every later
stage reads it back from the handoff file instead of re-deriving a slug that
would drift from the original.

Empty input, or an issue number `gh` cannot fetch: say so and stop. Analyzing
a guess produces a diagnosis nobody asked for.

With an issue number, run Part A of
[`../skill-pipeline-common/handoff-format.md`](../skill-pipeline-common/handoff-format.md)
§ "Searching for existing pull requests" now, before any analysis. A PR that
already fixes the issue makes the rest of this stage wasted work.

## Clarity check

| Requirement | What it means |
| --- | --- |
| Clear problem statement | What is wrong, stated once, without hedging |
| Reproduction path | A skill invocation, a command, or steps that show the defect |
| Expected versus actual | What the guidance, grader, or script should have done, and what it did instead |

Rate the report CLEAR or UNCLEAR against the table.

UNCLEAR means say exactly which requirement is missing and stop. Guessing a
root cause for an ambiguous report wastes the ground-truth and classification
work that follows it, and hands the next stage a diagnosis built on a guess.

Ask how many times it was seen. A defect reproduced twice is a defect; one
that appeared in a single session may be model variance wearing the costume
of a guidance gap, and a rule written from it encodes that session rather
than an invariant. This does not block the analysis. Record the count in the
handoff so the later stages know how much weight the evidence carries, and
prefer an advisory outcome over a hard rule when the count is one.

## Locate the defect

Grep `skills/`, `graders/`, `eval.yaml`, `scripts/`, and `dev/` for the
behavior, command, or claim the report names. Name the file and the line for
every hit that matters: the prose sentence, the check function, the script
line, or the eval task. A root cause with no `file:line` is not a root cause,
it is a hunch with a citation missing.

With those files named, run Part B of the existing-PR search in
[`../skill-pipeline-common/handoff-format.md`](../skill-pipeline-common/handoff-format.md)
§ "Searching for existing pull requests" on their paths. This is the only
check that runs on free-text input, which has no issue number for Part A.

## Ground truth

Many reports here are claims about how Infrahub behaves, not claims about this
repository's prose. Before writing the root cause, verify each such claim
against real Infrahub source at a specific version, and check whether the
behavior was already fixed upstream: guidance that was correct for an older
release is a version-scoped rule, not a bug. Run the ladder in
[`../skill-pipeline-common/ground-truth.md`](../skill-pipeline-common/ground-truth.md)
before the root cause paragraph, not after it. The rung used, the tag or
version, and the SHA (or `UNVERIFIED`) go in the handoff header's
`Ground truth` field.

## Classify the defect

| Defect class | What is wrong | Failing test surface |
| --- | --- | --- |
| `guidance` | A skill's prose, rule, or example gives wrong or version-stale instruction | An eval task plus a grader check that fails against the current prose |
| `grader` | A check function exists but cannot fail, or asserts the wrong thing | A pytest against the check function, run over four fixtures |
| `script` | A bundled script, or a registration/category-prefix surface, has drifted | A pytest against the script |

Registration drift (a skill missing from one of its registration surfaces)
and category-prefix drift (a rule file named outside its registered prefixes)
are `script`, not a fourth class: both are detectable by comparing the tree
against the surfaces in `skill-registration.md`, and
`check-skill-registration.py`, `check-cli-invocations.py`,
`check-plugin-freshness.py`, and `check-symlinks.py` already do exactly
this kind of comparison. There is no defect class with no test surface.

## Coverage check

Check whether an eval task, a grader check, or a pytest already covers this
behavior. If one exists and passes despite the defect, the test is wrong too,
not just the guidance, the grader, or the script: say so, and make fixing the
test part of the fix strategy rather than leaving it for the next stage to
discover on its own.

## Minimum change rung

Run the ladder in
[`../../../dev/guidelines/minimum-change.md`](../../../dev/guidelines/minimum-change.md)
before proposing a fix shape. Read it now, at the point of decision, not
after a strategy is already written around the wrong rung. Record which rung
the fix stops at and one line of why it does not need to go further, in the
handoff's `Minimum change rung` field.

## Fix strategy

State the approach and its scope: which file or files change, what stays
untouched, and a `Do NOT` list of the artifacts the minimum-change rung rules
out. This is the strategy the next stages execute, not the patch itself: no
diff, no fix code, no test code belongs here.

Name what this fix contradicts. Every existing rule, example, claim, or
command elsewhere in the repo that the fix corrects or supersedes goes in the
handoff's `Sweep terms` as a literal string to grep for.
`implementing-skill-changes` iterates that field and fixes every hit, so an
empty one turns its sweep into a no-op and leaves the old claim sitting next
to the new rule. `none` is a complete answer when the fix genuinely
contradicts nothing; blank is not, because it cannot be told apart from never
having looked.

Then work out what the fix leaves stale. A skill whose behavior changes keeps
every documentation surface it already had, and those surfaces go on
describing behavior it no longer has. Read
[`../../../dev/guidelines/skill-registration.md`](../../../dev/guidelines/skill-registration.md)
§ "When behavior changes" now, while the scope is in front of you, and run the
grep it gives. Record the answer in the handoff's `Docs impact` field. `none`
is a complete answer; a blank field is not, because it cannot be told apart
from never having looked.

## Output

1. Derive the default branch and fetch it, using the snippet in
   [`../skill-pipeline-common/handoff-format.md`](../skill-pipeline-common/handoff-format.md).
   Record the SHA. If the fetch fails, stop and report the failure rather than
   writing a handoff with a guessed baseline.
2. Write `.skill-change-<key>.md` at the repo root, following the template in
   the same file, with `Track: bug` and the `Defect class` set to exactly one
   of `guidance`, `grader`, `script`.
3. Confirm `.skill-change-*.md` is covered by `.gitignore`. It is a working
   file for this pipeline, not a repository artifact.
4. Display the analysis in full so the user can review it before the next
   stage reads it.

## Escalation

Stop and report rather than guessing forward, when:

- the input cannot be resolved to an issue or a description
- the clarity check rates the report UNCLEAR
- exploration finds no root cause after checking `skills/`, `graders/`,
  `eval.yaml`, `scripts/`, and `dev/`
- ground truth contradicts the report: the current guidance is already right
- the default-branch fetch fails

## Common mistakes

| Mistake | Why it breaks the pipeline |
| --- | --- |
| Writing fix code or a test into the analysis | This stage produces a diagnosis, not a patch; the next stage owns the code |
| Analyzing an UNCLEAR bug | A root cause built on a guess sends the wrong fix downstream |
| Re-deriving the slug later in the pipeline | The key drifts from the one recorded in the handoff, and later stages lose the thread |
| Writing the analysis with no baseline SHA | Later stages cannot tell what the fix diverged from |
| Encoding an Infrahub behavior claim that ground truth never checked | A stale or version-specific claim ships as a correction |
| `git add`-ing the handoff file | `.skill-change-*.md` is a local working file, never a commit |

## Boundaries

Follow the repository-wide boundaries in
[`../../../AGENTS.md`](../../../AGENTS.md) § Boundaries.

Versions

The database has no other skills named analyzing-skill-bugs.

Database snapshot: 13.11.2026 · package version 28129c12ca15 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100grilling-skill-features
    Stress-tests a raw idea for this repository's skills until it is a design a grader can actually test, before any rule, eval, or skill is written. Follow the workflow in the body; the description does not summarize it. TRIGGER when: someone has a fuzzy idea for new guidance in an…
  • 100test-driving-skill-changes
    Writes the failing test for an analysed or grilled skill change, and proves it fails, before any fix is written. Chooses the test surface from the defect class: an eval.yaml task plus a grader check for guidance, a pytest for grader and script defects. Follow the workflow in the…
  • 100opsmill-dev-analyzing-bugs
    Performs root-cause analysis of a bug — from a GitHub issue, an issue URL, or a free-text description — before any reproduction or fix is written. TRIGGER when: triaging or diagnosing a bug, investigating why something misbehaves, an issue number/URL handed over for analysis,…
  • 100opsmill-dev-test-driving-bugs
    Writes a single failing test that reproduces a bug after its root-cause analysis is complete, before any fix is written. TRIGGER when: a bug has a completed root-cause analysis and you need the failing reproduction test, writing a test that proves a bug exists, the second step…
  • 95agent-observability-trace-rca
    Root cause analysis on production LLM traces. Diagnoses why an LLM application is failing — works from eval judge verdicts, runtime errors, or structural anomalies depending on what signals are present. Walks the span tree from symptom to root cause. Use when user says "what's…
  • 100trace
    Use when encountering bugs, test failures, runtime errors, broken builds, or "this doesn't work" reports. Systematic root-cause analysis before any patch — never blind-patches symptoms. Standalone, ends with a final-integration review of the fix. Trigger with /hyperflow:trace,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.