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.
In this repository14 other files it gives its agents.
- analysisSkill
- critiqueSkill
- domain-modelingSkill
- fetch-paperSkill
- grillingSkill
- grill-with-docsSkill
- handoffSkill
- implementSkill
- literature-reviewSkill
- project-knowledgeSkill
- proposalsSkill
- read-aloudSkill
- referencesSkill
- update-project-knowledgeSkill
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
- Very specific: line 15
If the change introduces a new method, alternative algorithm, or evaluation strategy, it is not a fix — use /proposals instead.
- Distinctive: line 46
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 …
- Distinctive: line 54
If the user wants to skip the document and just have it implemented, do that and stop — the skill ends here.
- Distinctive: line 64
Ask only what you can't already infer from the conversation.
- Distinctive: line 70
After collecting answers, summarize the fix in structured form and ask: "Does this reflect the fix?
- Very specific: line 79
Write the fix document to: docs/fixes/{fix-id}.md
- Very specific: line 80
Use the template at .claude/skills/fixes/templates/fix.md.
- Very specific: line 82
Only include a ## References section if Phase 0 grounding was actually invoked.
- Very specific: line 126
All fix documents live in docs/fixes/
- Very specific: line 129
When creating a new fix doc, check if a similar one already exists first (Glob docs/fixes/*.md and scan titles)
≈ “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.
Files
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:
/fixesor/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 editsPhase 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
- State plainly what is broken and why it's a fix and not a proposal (one sentence).
- 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.
- 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):
- What's broken: "What's the current incorrect behavior, and what should it be instead?"
- Scope: "Which files/functions need to change?" (infer from code if obvious, confirm rather than ask from scratch)
- 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
- 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. - Write the fix document to:
docs/fixes/{fix-id}.md - Use the template at
.claude/skills/fixes/templates/fix.md. - Fill all sections with substantive content — no placeholder text.
- Only include a
## Referencessection if Phase 0 grounding was actually invoked; omit it otherwise (per the project'sreferences.mdrule: 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
| File | Scope | Nature of change |
| {file.py} | {ClassName / function_name} | {what changes} |
3. Plan
Ordered, actionable implementation steps with effort estimates.
1. {step} — effort: low | medium | high4. 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/*.mdand scan titles)
Synergy with other skills
| Skill | When to invoke |
/references | Phase 0, only if the fix's motivation rests on an unverified external claim |
/proposals | If discovery reveals the change is actually introducing a new method/alternative rather than correcting existing behavior — redirect there instead |
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
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.

