agentleFS
arthur-plautzarthur-plautz/research-toolkit/.claude/skills/fixes/SKILL.md

fixes

Skill0 starsChanged 4 months agoMITView on GitHub

Manages bug fixes and implementation corrections — behavior that deviates from spec, an unscaled constant, a broken invariant, a paper-reproducibility mismatch. Guides the agent through a short discovery-confirmation-formalization flow that produces a lightweight fix document under docs/fixes/. Lighter weight than /proposals — no new method or alternative is being introduced.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 4 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the change introduces a new method, alternative algorithm, or evaluation strategy, it is not a fix — use /proposals instead.

    line 15
  2. Distinctive:

    If grounding is needed and the claim turns out to be wrong (as opposed to the code), stop — there's no fix to make, the prior claim was the …

    line 46
  3. Distinctive:

    If the user wants to skip the document and just have it implemented, do that and stop — the skill ends here.

    line 54
  4. Distinctive:

    Ask only what you can't already infer from the conversation.

    line 64
  5. Distinctive:

    After collecting answers, summarize the fix in structured form and ask: "Does this reflect the fix?

    line 70
  6. Very specific:

    Write the fix document to: docs/fixes/{fix-id}.md

    line 79
  7. Very specific:

    Use the template at .claude/skills/fixes/templates/fix.md.

    line 80
  8. Very specific:

    Only include a ## References section if Phase 0 grounding was actually invoked.

    line 82
  9. Very specific:

    All fix documents live in docs/fixes/

    line 126
  10. Very specific:

    When creating a new fix doc, check if a similar one already exists first (Glob docs/fixes/*.md and scan titles)

    line 129

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Purpose

This skill governs how bug fixes and implementation corrections are handled. A fix is any change that corrects existing behavior rather than introducing a new method or alternative:

  • A hardcoded constant that should scale with another quantity (e.g. a generation count that should be a fraction of the step budget)
  • A broken invariant (e.g. an inverted axis, a stat column in the wrong order)
  • A mismatch against a paper's reported method or a reproducibility baseline
  • A bug in a pipeline step that produces incorrect output

If the change introduces a new method, alternative algorithm, or evaluation strategy, it is not a fix — use /proposals instead. The dividing line: a fix makes the current approach correctly do what it was already supposed to do; a proposal changes what the approach does.

This skill is intentionally lighter than /proposals: no ## Description, ## Method, or mandatory ## References section, no Phase 0 discovery sweep. References are only pulled in if the fix touches a claim that needs grounding (e.g. "the paper says X" must be checked against the actual paper, not memory).


When to invoke

  • User says "fix", "correct", "this is wrong", or describes a bug/deviation rather than an alternative
  • User wants to turn an agreed-upon correction (e.g. from a prior discussion) into a tracked change
  • User wants to view, update, or refer back to an existing fix document
  • Invoke explicitly: /fixes or /fixes edit <fix-id>

Flow

Phase 0: Grounding (conditional)  →  invoke /references only if a claim needs verifying
Phase 1: Confirmation              →  confirm the fix is in scope and worth tracking
Phase 2: Elicitation               →  enter plan mode → short Q&A
Phase 3: Formalization             →  write fix document to docs/fixes/
Phase 4: Edit mode                 →  (optional) read existing fix → targeted edits

Phase 0 — Grounding (conditional)

Only invoke /references if the fix's motivation rests on a claim from a paper, prior result, or external source that hasn't already been verified in this conversation (e.g. "the paper specifies X" or "this contradicts the baseline run"). Skip entirely if the bug is self-evident from reading the code (e.g. an inverted comparison, an unscaled constant, a column-order mismatch).

If grounding is needed and the claim turns out to be wrong (as opposed to the code), stop — there's no fix to make, the prior claim was the error. Correct the claim in conversation instead.


Phase 1 — Confirmation

  1. State plainly what is broken and why it's a fix and not a proposal (one sentence).
  2. Ask: "Should I write this up as a tracked fix, or is this small enough to just implement directly?" — not every correction needs a document. Use judgment: cross-file changes, anything touching reproducibility invariants, or anything the user may want to reference later warrants a doc. A one-line typo fix does not.
  3. If the user wants to skip the document and just have it implemented, do that and stop — the skill ends here.

Checkpoint: User has confirmed they want a fix document before plan mode is entered.


Phase 2 — Elicitation (Plan Mode)

Enter plan mode immediately after confirmation.

Ask only what you can't already infer from the conversation. Suggested question sequence (skip any already answered):

  1. What's broken: "What's the current incorrect behavior, and what should it be instead?"
  2. Scope: "Which files/functions need to change?" (infer from code if obvious, confirm rather than ask from scratch)
  3. Risk: "Does this touch anything reproducibility-sensitive (paper baselines, invariant stat columns/axes)? If so, what's the verification step before/after?"

After collecting answers, summarize the fix in structured form and ask: "Does this reflect the fix? Shall I write the document?"

Checkpoint: User approves the summary before the document is written.


Phase 3 — Formalization

  1. Generate a unique fix ID using the format: YYYY-MM-DD-{topic-slug} (e.g., 2026-06-21-warmup-step-fraction). The slug is 3–5 words in kebab-case.
  2. Write the fix document to: docs/fixes/{fix-id}.md
  3. Use the template at .claude/skills/fixes/templates/fix.md.
  4. Fill all sections with substantive content — no placeholder text.
  5. Only include a ## References section if Phase 0 grounding was actually invoked; omit it otherwise (per the project's references.md rule: omit if no claims are cited).

Announce the file path to the user after writing: Fix written to docs/fixes/{fix-id}.md.


Fix document structure

1. Problem

What's currently wrong. State the incorrect behavior and, if relevant, where it deviates from a paper, baseline, or invariant. Be concrete — name the file/line, the wrong value, the expected value.

2. Impact

FileScopeNature of change
{file.py}{ClassName / function_name}{what changes}

3. Plan

Ordered, actionable implementation steps with effort estimates.

1. {step} — effort: low | medium | high

4. Verification

How to confirm the fix works and didn't break anything else — which tests, which reproducibility check, which experiment to rerun.

5. References (only if Phase 0 grounding occurred)

Standard /references table format.


Fix template

See .claude/skills/fixes/templates/fix.md.


Naming and indexing

  • All fix documents live in docs/fixes/
  • File name: {YYYY-MM-DD}-{topic-slug}.md
  • Status field values: draft, active, implemented
  • When creating a new fix doc, check if a similar one already exists first (Glob docs/fixes/*.md and scan titles)

Synergy with other skills

SkillWhen to invoke
/referencesPhase 0, only if the fix's motivation rests on an unverified external claim
/proposalsIf discovery reveals the change is actually introducing a new method/alternative rather than correcting existing behavior — redirect there instead

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.