---
description: Check Gitea for open issues and surface the next task to work on
---

# Backlog - Find Next Task

## Core Workflow

### Step 1: Detect the current repo

Extract the Gitea `owner/repo` from the git remote:

```bash
# Extract owner/repo from the git remote URL
# Adapt the pattern to match your Gitea hostname
git remote get-url origin 2>/dev/null | sed -n 's|.*://[^/]*/\(.*\)\.git|\1|p'
```

If no Gitea remote is found, ask the user which repo to check.

### Step 2: Fetch open issues from Gitea

**Primary method — use `gitea-mcp` MCP server:**

Use ToolSearch to load `mcp__gitea-mcp__list_repo_issues`, then call it:

```
mcp__gitea-mcp__list_repo_issues(owner="{owner}", repo="{repo}", state="open", type="issues", limit=20)
```

**Fallback — if MCP is unavailable, use curl:**

```bash
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/repos/{owner/repo}/issues?state=open&type=issues&limit=20&sort=priority" \
  | python -m json.tool
```

**Gitea API base:** `$GITEA_URL/api/v1`
**Auth token:** `$GITEA_TOKEN` environment variable

### Step 3: Branch based on results

#### Path A: Open issues exist

Present issues to the user as numbered options:

```
Found 3 open issues for owner/repo:

1. #12 — Add dark mode toggle (enhancement)
   Labels: feature, ui
   Created: 2d ago

2. #10 — Fix audio recording on Wayland (bug)
   Labels: bug, audio
   Created: 5d ago

3. #8 — Add export to markdown (feature)
   Labels: feature
   Created: 1w ago

Which issue would you like to work on?
```

Include: issue number, title, labels, relative age. If there are many issues, show the top 5-7 most relevant (prioritize bugs, then features, then enhancements).

#### Path B: No open issues — scan for TODOs

Use Grep to scan the codebase for TODO/FIXME/HACK/XXX markers:

```
Grep pattern: "(TODO|FIXME|HACK|XXX):?\s"
```

**Exclude:** `.git/`, `node_modules/`, `__pycache__/`, `.venv/`, `*.lock`, `*.min.*`

For each TODO found:
1. Read surrounding context (a few lines around the match)
2. Group related TODOs if they're in the same function/section
3. Create a Gitea issue for each distinct task:

**Primary method — use `gitea-mcp` MCP server:**

Use ToolSearch to load `mcp__gitea-mcp__create_issue`, then call it:

```
mcp__gitea-mcp__create_issue(owner="{owner}", repo="{repo}", title="Clear, actionable title", body="Found in `file/path.py:42`:\n\n```\n# TODO: the original comment\n```\n\nContext: brief description.")
```

**Fallback — if MCP is unavailable, use curl:**

```bash
curl -s -X POST \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  "$GITEA_URL/api/v1/repos/{owner/repo}/issues" \
  -d '{
    "title": "Clear, actionable title derived from the TODO",
    "body": "Found in `file/path.py:42`:\n\n```\n# TODO: the original comment\n```\n\nContext: brief description of what needs to be done.",
    "labels": []
  }'
```

After creating issues, present them as options (same format as Path A).

#### Path C: No issues and no TODOs

```
No open issues and no TODO markers found in owner/repo.
The backlog is clear — nice work!
```

## Issue Creation Guidelines

- **Title:** Imperative verb form, concise ("Add export feature", "Fix audio clipping on short recordings")
- **Body:** Include the file path and line number, the TODO text, and brief surrounding context
- **Deduplication:** Before creating, check if an open issue with a very similar title already exists
- **Grouping:** If multiple TODOs clearly relate to the same task (e.g., in the same function), combine them into one issue

## Key Principles

1. Always detect repo from git remote — don't hardcode repos
2. Present options clearly so the user can pick their next task quickly
3. Only create issues for genuine TODOs, not commented-out code or documentation examples
4. Keep issue titles actionable and concise