agentleFS
Sign inStart free
r3bl-orgr3bl-org/r3bl-open-core/.agents/skills/fix-issue/SKILL.md

fix-issue

Skill486 starsChanged 15 days agoApache-2.0View on GitHub

This skill codifies the "slow and steady" approach to solving non-trivial issues or adding features. It enforces exploring the problem space, considering alternative designs, and formalizing the design before writing any implementation code. Use this skill whenever you are: The workflow consists of four distinct steps: Before proposing any changes or writing a task file, gather context on the problem space: Create the task file under task/issue-<id>-fix.md or task/<name>.md. Create a new git branch for this task, push it, and…

  • Commits and pushes

We split this skill into the rules it gives an agent

12 rules. 0 are common, 6 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 49 edited versions we read keep these.

  • 6

    Distinctive

    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. Distinctive:

    Use this skill whenever you are:

    line 16
  2. Distinctive:

    Before proposing any changes or writing a task file, gather context on the problem space:

    line 35
  3. Very specific:

    Read the issue description (e.g., via gh issue view <id>).

    line 37
  4. Distinctive:

    Search the codebase to locate all relevant files, traits, types, and usages.

    line 38
  5. Very specific:

    Do NOT write or modify any source code or run cargo check during this step.

    line 40
  6. Very specific:

    Create the task file under task/issue-<id>-fix.md or task/<name>.md.

    line 44
  7. Very specific:

    Create a new git branch for this task, push it, and open a Draft PR using gh pr create --draft --fill to track the work.

    line 45
  8. Distinctive:

    Instead of a simple todo list, format this task file as a Design Document with the following sections:

    line 53
  9. Distinctive:

    Every phase MUST end with a Mandatory manual review checkbox list for modified files.

    line 90
  10. Distinctive:

    Ask for feedback and wait for explicit approval before proceeding to implementation.

    line 98
  11. Very specific:

    Only after the design doc is approved, load the task (ideally in a fresh or /compact-ed context if Step 1 read many unrelated files) and …

    line 102
  12. Very specific:

    Verify each step with ./check.fish --check (which runs cargo check -q --message-format=short) and pause for manual reviews frequently.

    line 104

“Common” is measured: kept by at least 6 in 10 of the 49 edited versions of this file we could read. “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

Issue Fix Workflow: Deep Exploration and Design

This skill codifies the "slow and steady" approach to solving non-trivial issues or adding features. It enforces exploring the problem space, considering alternative designs, and formalizing the design before writing any implementation code.

When to Use

Use this skill whenever you are:

  • Creating a new task file for a non-trivial issue or feature.
  • Asked by the user to "explore first", "design first", or "write a design doc".
  • Working on complex or architectural changes that span multiple components.

The Design-First Workflow

The workflow consists of four distinct steps:

┌───────────────────┐      ┌───────────────────┐      ┌───────────────────┐      ┌───────────────────┐
│ 1. Deep Research  │ ───► │  2. Design Doc    │ ───► │  3. User Review   │ ───► │ 4. Implementation │
│ (No Code Written) │      │  (Task MD File)   │      │   & Approval      │      │ (Iterative Step)  │
└───────────────────┘      └───────────────────┘      └───────────────────┘      └───────────────────┘

Step 1: Deep Research (No Code Written)

Before proposing any changes or writing a task file, gather context on the problem space:

  1. Read the issue description (e.g., via gh issue view <id>).
  2. Search the codebase to locate all relevant files, traits, types, and usages.
  3. Understand the control flow, thread boundaries, and lifecycle constraints.
  4. Do NOT write or modify any source code or run cargo check during this step.

Step 2: Design Doc (Task File Creation)

Create the task file under task/issue-<id>-fix.md or task/<name>.md. Create a new git branch for this task, push it, and open a Draft PR using gh pr create --draft --fill to track the work.

[!TIP] If creating a linked git worktree for the task, always use relative paths (or set git config --global worktree.useRelativePaths true) so the worktree remains portable across remote fleet machines (Linux and macOS):

git worktree add --relative ../roc-<name> <branch_name>

Instead of a simple todo list, format this task file as a Design Document with the following sections:

1. Overview

  • Clear statement of the goal.
  • Context and reference to GitHub issues or PRs.

2. Problem Space & Constraints

  • Detailed analysis of the current code.
  • Specific limitations of the existing design.
  • Architectural and safety constraints (e.g., thread safety, locks, lifetimes, platform compatibility).

3. Design Alternatives

Present at least two (ideally three) alternative approaches. For each alternative, detail:

  • How it works: High-level explanation of the API and structural changes.
  • Pros: Benefits of this approach.
  • Cons: Drawbacks, complexity, or limitations.
  • Assessment: Feasibility, effort, and alignment with the project's design philosophy.

4. Proposed Design

  • Which alternative was chosen and why.
  • Exact Rust API signatures, type changes, struct definitions, and target file paths so implementation steps can be executed deterministically.
  • Visual diagram (if applicable, using ASCII or flowchart LR Mermaid).
  • Threading, lock, and lifecycle impact analysis.

5. Implementation Plan

The very last section containing flat checklists grouped under phase headers.

  • Phase 1: Preparation / API Refactoring
  • Phase 2: Core Implementation
  • Phase 3: Integration & Testing
  • Every phase MUST end with a Mandatory manual review checkbox list for modified files.

Step 3: User Review & Approval

Present the newly created task file to the user.

  • Highlight the design alternatives and the proposed design.
  • Ask for feedback and wait for explicit approval before proceeding to implementation.

Step 4: Iterative Implementation

Only after the design doc is approved, load the task (ideally in a fresh or /compact-ed context if Step 1 read many unrelated files) and begin implementation step-by-step:

  • Verify each step with ./check.fish --check (which runs cargo check -q --message-format=short) and pause for manual reviews frequently.

Step 5: Merge & Complete

Once the implementation is fully tested and manually reviewed:

  • Remind the user to run the /merge-pr slash command to push the final code and merge the existing Pull Request into main.

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.

Check your setup, free