---

name: update-issue description: "Update external issue tracker (GitHub/GitLab) based on Ralf events. Use when syncing story status with project management tools."

Update Issue Skill

Expert guidance for updating issue status in external trackers based on Ralf events.

When to Use

• Syncing story status with GitHub Issues
• Updating GitLab issues during Ralf execution
• Automating issue tracker updates via hooks
• Manual status updates via command

Supported Platforms

GitHub (via gh CLI or MCP)

Copy# Add label
gh issue edit <issue_number> --add-label "in-progress"

# Remove label
gh issue edit <issue_number> --remove-label "in-progress"

# Add comment
gh issue comment <issue_number> --body "Starting implementation..."

# Close issue
gh issue close <issue_number> --comment "Completed!"

GitLab (via MCP GitLab Server)

Use the MCP GitLab tools when available:

• mcp__noqta_gitlab_server__update_issue - Update issue attributes
• mcp__noqta_gitlab_server__create_issue_note - Add comments

Or via glab CLI:

Copy# Update labels
glab issue update <issue_number> --label "in-progress"

# Add comment
glab issue note <issue_number> --message "Starting implementation..."

# Close issue
glab issue close <issue_number>

Story ID Formats

The skill auto-detects issue format from story ID:

Issue Mapping

For custom story IDs, add mapping to prd.json:

Copy{
  "userStories": [
    {
      "id": "US-001",
      "title": "Add login",
      "issueRef": {
        "platform": "github",
        "number": 42
      }
    }
  ]
}

Status Mapping

Platform Detection

Auto-detect platform from git remote:

Copy# Get remote URL
REMOTE=$(git remote get-url origin)

# Check platform
if [[ "$REMOTE" == *"github.com"* ]]; then
  PLATFORM="github"
elif [[ "$REMOTE" == *"gitlab"* ]]; then
  PLATFORM="gitlab"
fi

Hook Integration

The update-issue skill is typically invoked via lifecycle hooks:

Copy# In .ralf/hooks/on-task-start.sh
STORY_ID=$(echo "$CONTEXT" | jq -r '.storyId')

if [[ "$STORY_ID" =~ ^#([0-9]+)$ ]]; then
  ISSUE_NUM="${BASH_REMATCH[1]}"
  gh issue edit "$ISSUE_NUM" --add-label "in-progress"
fi

Configuration

Project-level configuration in .ralf/config.json:

Copy{
  "settings": {
    "issueTracker": {
      "platform": "github",
      "autoUpdate": true,
      "labelOnStart": "in-progress",
      "labelOnComplete": null,
      "labelOnBlocked": "blocked",
      "closeOnComplete": false
    }
  }
}

Error Handling

• If issue doesn't exist: Log warning, continue
• If label doesn't exist: Create it or skip
• If API rate limited: Retry with backoff
• If auth fails: Log error, don't block execution

Best Practices

1. Use optional hooks: Don't block Ralf execution on issue tracker failures
2. Keep comments concise: Include key metrics, not full logs
3. Use consistent labels: Define label set in project config
4. Handle missing issues: Story may not have corresponding issue

Example Comment Templates

On Start

CopyStarting implementation on branch `ralf/feature-name` (iteration 1)

On Complete

CopyCompleted in 5m 30s using 25,000 tokens.

Commit: `abc123def`
Files changed: src/auth.ts, src/login.tsx

On Blocked

CopyBlocked after 3 attempts.

**Reason:** Typecheck failed - missing dependency

**Errors:**
- Cannot find module 'auth-lib'
- Type 'User' is not assignable to type 'AuthUser'

Manual intervention required.