r3bl-open-core: Skill for Claude Code

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>