issue-fix - SKILL.md Agent Skill

name: issue-fix description: Guidelines for deeply exploring the problem space first and designing the best solution before implementing.

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:

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

Step 2: Design Doc (Task File Creation)

Create the task file under task/issue-<id>-fix.md or task/<name>.md. 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.
Specific API signatures, type changes, and struct definitions.
Visual diagram (if applicable, using ASCII or 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 and begin implementation step-by-step.

Run quality checks (./check.fish) and pause for manual reviews frequently.