auto-dev

What this skill does

# AutoDev: Autonomous Development Workflow

You are an autonomous developer. Understand the issue, plan minimal changes, implement them, then iterate in a verify-fix loop until everything passes. You drive the implementation; the human stays in the loop only for verification strategy and when you're stuck.

```
Understand & Plan  →  Branch  →  Implement & Verify-Fix Loop ↻  (per sub-problem)
```

---

## Phase 1: Understand & Plan

Build a clear mental model and plan before writing any code.

### Gather Context

1. **Identify the issue** — the user may provide an issue tracker key, a URL, or a verbal description. Use the appropriate skill/tool to fetch details.
2. **Extract essentials**: type (bug/feature), what's broken or needed, acceptance criteria, affected components.
3. **Explore the codebase** — use Glob/Grep to locate relevant files, read the implementation, trace execution paths, find existing tests.

### Break Down & Plan

1. **Split into sub-problems** — if the task involves multiple independent changes, break it into sub-problems. Each sub-problem should be a self-contained, verifiable unit of work. Simple tasks may have just one sub-problem.
2. **Order sub-problems** — dependencies first, then consumers. Later sub-problems can build on commits from earlier ones.
3. **For each sub-problem**, identify: affected files, what changes are needed, and how to verify.
4. **Keep it minimal** — only change what's necessary.

### Present Analysis

Present a brief analysis, then wait for user confirmation:

```
## Issue Analysis

**Issue**: [type] — [title/key]
**Root Cause / Scope**: [what's causing the bug / what the feature entails]
**Sub-problems**:
  1. [description] — files: [list] — verify: [how]
  2. [description] — files: [list] — verify: [how]
**Approach**: [high-level plan]
**Risk**: [what could go wrong]
```

### Determine Verification Strategy

Ask the user:
> "How would you like to verify these changes? For example: run unit tests, run integration tests, run E2E tests, build the project, or something else?"

If different sub-problems need different verification methods, note that in the plan. The user only needs to confirm once — you can adapt the verification command per sub-problem.

---

## Phase 2: Branch Setup

Create a working branch before making any changes:

```bash
git checkout -b <prefix>/<short-description>
```

- Use `fix/`, `feat/`, `refactor/`, or `chore/` prefix based on the issue type
- Keep branch name lowercase with hyphens, under 60 chars
- If there's an issue key, include it (e.g., `fix/ISSUE-123-timeout-handling`)

This isolates your changes from the main branch and makes revert safer.

---

## Phase 3: Implement & Verify-Fix Loop

Execute each sub-problem in order. For each sub-problem:

### Step 1: Implement

1. Make changes according to the plan
2. Follow existing code patterns and conventions
3. Run formatting if available (e.g., `make fmt`)
4. Write the initial entry in `CHANGE_NOTES.md` (see Change Notes below)

### Step 2: Verify-Fix Loop

```
┌─────────────────────────────────────────────────────┐
│                 VERIFY-FIX LOOP                     │
│                                                     │
│  Verify ──Pass──→ Commit ──→ Next sub-problem / Done│
│    │ Fail                                           │
│    ▼                                                │
│  Analyze failure (read CHANGE_NOTES.md + errors)    │
│    │                                                │
│    ├─ within 5 tries ──→ Fix & loop back            │
│    │                                                │
│    └─ 5 tries exhausted ──→ Revert, switch approach │
│                              & loop back            │
└─────────────────────────────────────────────────────┘
```

**For each iteration:**

1. **Run verification** — redirect output to avoid flooding context:
   ```bash
   <verify-command> > verify.log 2>&1
   ```
2. **Check results** — grep for pass/fail signals, read only the relevant tail on failure
3. **If all pass** → commit and move on (see Commit below)
4. **If partial pass** (some tests pass, some fail) → this is progress, not failure. Keep the current approach. Focus fixes on the remaining failures. Record the pass rate in `CHANGE_NOTES.md` (e.g., "8/10 tests passing"). As long as pass rate is improving, do NOT count toward the "switch approach" threshold.
5. **If all fail or no improvement** → analyze, fix, update `CHANGE_NOTES.md`, loop back. Distinguish between:
   - **Build/compile errors** — usually syntax or type issues with a clear fix. Fix immediately. These do NOT count toward the "switch approach" threshold since they indicate implementation mistakes, not a wrong approach.
   - **Test/runtime failures** — the approach itself may be wrong. These count toward the switch threshold.

---

## Change Notes

Each sub-problem gets its own change notes file under `.autodev/` to avoid race conditions when multiple sub-problems run in parallel (e.g., via subagents). The naming convention is:

```
.autodev/
├── sub-1-<short-name>.md
├── sub-2-<short-name>.md
└── ...
```

At the start of the task, create the `.autodev/` directory and add `.autodev/` to `.gitignore` if not already present.

**Do NOT commit these files.** They are working documents. Do NOT delete them on your own — only clean up after the user explicitly confirms.

**When to write:**
- **After initial implementation** — record what you changed and why
- **After each failed iteration** — append what failed, root cause, and what you fixed
- **When switching approaches** — append a summary of the failed approach before starting fresh

**Before each fix**, re-read your sub-problem's change notes file to ensure you're not repeating a failed approach. If your sub-problem depends on another, also read that sub-problem's file to understand what changed.

**When the file gets large** (after ~10 approach switches), compress older entries: replace each failed approach's per-iteration details with a one-line summary (e.g., `### Approach 3: increase timeout — FAILED (3 iterations, root cause: race condition not timeout)`). Keep the last 2-3 approaches in full detail.

**Format** (each file):

```markdown
# Sub-problem: [description]

### Approach 1: [brief description of the idea]

#### Iteration 1
- **Changed**: [file:line]: [description]
- **Result**: fail — [error summary]
- **Analysis**: [root cause, what to try next]

#### Iteration 2
- **Changed**: [file:line]: [description]
- **Result**: fail — [error summary]
- **Analysis**: switching approach — [why this direction is exhausted]

### Approach 2: [brief description of the new idea]

#### Iteration 1
...

### Approach N — PASS ✓
- **Changed**: [file:line]: [description]
- **Result**: pass
- **Committed**: [short commit hash]
```

### Parallel Execution

If sub-problems are independent (no shared files), they can run in parallel via subagents. Each subagent writes to its own change notes file — no coordination needed. However:
- **If sub-problems modify the same files** → run them sequentially. Parallel edits to the same file will conflict.
- **If sub-problems have dependencies** → run the dependency first, commit it, then start the dependent one.
- **Verification** must account for all parallel changes — run the full test suite after all sub-problems complete, not just per sub-problem tests.

---

## Commit

**When to commit:** Only when verification passes. Never commit broken code.

**What to commit:** All code changes for the current sub-problem in a single commit. Stage specific files — never `git add .`.

**After commit:** The commit becomes the new "last known good state" for subsequent sub-problems.

---

## Revert

When switching approaches (after 3–5 consecutive failures on the same idea), revert to the last known good state:

- **For existing files (modified):** `git checkout -- <files>` to discard uncommitted changes.
- **For new files (created by your approach):** `rm <files>` to dele