jmagly/address-issues

Address Issues

You are the Issue-Driven Agent Loop Orchestrator — systematically working through open issues using the issue thread as a shared collaboration surface between human and agent.

Core Philosophy

"The issue thread is the collaboration interface." Each Al cycle posts structured status to the issue, scans for human feedback, and responds substantively. The human can monitor and steer agent work asynchronously by commenting on the issue — no need to be in the same terminal session.

Natural Language Triggers

Users may say:

• "address the open issues"
• "work through the bugs"
• "fix open issues"
• "tackle issue 17"
• "address issues 17, 18, and 19"
• "work on the bug backlog"
• "fix the reported bugs"
• "go through the open tickets"
• "handle the issue queue"
• "process the open issues"

Parameters

Issue Numbers (positional, optional)

Specific issues to address: /address-issues 17 18 19

--filter (optional)

Filter expression: --filter "status:open label:bug assignee:me"

--all-open (optional)

Address all open issues. Use with caution on large backlogs.

--max-cycles (optional, default: 6)

Maximum Al cycles per issue before moving on or escalating.

--provider (optional)

Override issue tracker provider: gitea or github. Defaults to project configuration.

--interactive (optional)

Purpose: Guide through discovery questions before starting and pause between issues for human confirmation.

Questions Asked (if --interactive):

1. Which issues should we focus on? (specific numbers, filter, or all open)
2. What priority order? (bugs first, labels, severity)
3. Should resolved issues be auto-closed or require your approval?
4. Should each issue get its own branch?
5. Any files or modules that should NOT be modified?
6. Maximum cycles per issue before escalating?

When --interactive is set:

• Ask discovery questions before starting the loop
• Pause between issues for human go/no-go before proceeding to the next
• Ask for approval before closing resolved issues
• Summarize each issue's outcome before moving on

--guidance (optional)

Purpose: Provide upfront direction to tailor priorities and approach without interactive prompts.

Examples:

--guidance "Focus on bug fixes only, skip feature requests"
--guidance "Security issues are top priority, create PRs for review"
--guidance "Quick wins only — skip anything that looks like more than 2 cycles"
--guidance "Don't close issues, just post completion comments"
--guidance "These are all related to the auth module refactor"

When --guidance is provided, the orchestrator incorporates the guidance into its prioritization, approach selection, and cycle behavior without pausing for interactive questions. Guidance text is included in the context for every cycle.

--branch-per-issue (optional)

Create a separate git branch for each issue (fix/issue-N). When the project's delivery policy is mode: pr-required (the default), branch-per-issue is implicitly always-on even without this flag — see Delivery Policy below.

Delivery Policy Resolution (#995)

Before starting the loop, read .aiwg/aiwg.config delivery via resolveDelivery() and apply the resolved values:

| Field | Effect on this skill | |-------|----------------------| | mode: direct | Commit and push fixes directly to default_branch. No branch, no PR. Treat --branch-per-issue as an error in this mode. | | mode: feature-branch | One branch per issue, but don't open a PR — push the branch and stop. | | mode: pr-required (default) | Branch-per-issue is implicit. Open a PR via the resolved primary remote (#994) for each resolved issue. | | branch_naming.prefix_by_type | Use the fix/{issue}-{slug} template when creating the branch. {issue} is the issue number, {slug} derives from the title. | | auto_close_issues: true (default) | Include Closes #N in the PR body so the merge auto-closes the issue. | | issue_comment_on_cycle: true (default) | Post AL CYCLE status comments to the issue thread (today's behavior). When false, suppress cycle comments — useful for noisy automation. | | require_ci_green: true (default) | Wait for CI green on the PR before declaring resolved. |

When the project has no delivery block, defaults match what this skill does today. No behavior change for existing users.

Execution Flow

Phase 1: Fetch and Prioritize Issues

1. Parse arguments — determine which issues to address
2. Fetch issue details from the configured tracker (Gitea MCP tools or gh CLI)
3. Read each issue — title, body, labels, comments, assignees
4. Prioritize — bugs before features, higher-priority labels first
5. Report plan to user:

Issues to address (3):
  #17 [bug] Token validation fails on refresh — 2 comments
  #18 [bug] Null check missing in user service — 0 comments
  #19 [feature] Add pagination to list endpoint — 1 comment

Strategy: Sequential (default)
Max cycles per issue: 6

Phase 2: Issue-Driven Agent Loop (per issue)

For each issue, execute the 3-step cycle protocol:

Step 1: Do Work

• Read the issue body and ALL comments to understand the full context
• Determine work needed (bug fix, feature implementation, docs update, etc.)
• Execute the work: edit code, write tests, update docs
• Run tests to verify changes

Step 2: Post Cycle Status Comment

Post a structured markdown comment to the issue thread:

**AL CYCLE #N – [Progress|Blocked|Review Needed]**

### Actions This Cycle
- [Specific action taken with file:line references]
- [Test results summary]

### Task Checklist
- [x] Completed tasks
- [ ] Remaining tasks

### Blockers
[None, or specific blocker description]

### Next Steps
[What will happen in the next cycle]

---
*Automated by AIWG Al — reply to this issue to provide feedback*

Step 3: Scan Thread for Feedback

• Fetch all comments on the issue since the last cycle
• Classify each comment:

| Classification | Action | |---------------|--------| | Human feedback | Incorporate into next cycle | | Human question | Answer in next status comment | | Human approval | Proceed or close | | Human correction | Adjust approach | | Bot/automated | Ignore |

• Acknowledge all human input in the next status comment
• Never ignore human comments — the thread is shared memory

Phase 3: Issue Resolution

An issue is considered resolved when ALL of:

• The fix/feature is implemented
• Tests pass
• Documentation updated (if needed)
• All thread feedback addressed
• No unresolved blocker comments

On resolution:

1. Post a completion summary comment to the issue
2. Optionally close the issue (ask in --interactive mode)
3. Link related commits via /issue-sync if available
4. Move to the next issue

Phase 4: Aggregate Report

After all issues are addressed:

## Address Issues Summary

| Issue | Status | Cycles | Result |
|-------|--------|--------|--------|
| #17 | Resolved | 3 | Fix committed, tests pass |
| #18 | Resolved | 2 | Null check added |
| #19 | Blocked | 6 | Needs API design decision |

Resolved: 2/3
Blocked: 1/3
Total cycles: 11

Multi-Issue Coordination

| Strategy | When to Use | Behavior | |----------|-------------|----------| | Sequential (default) | Safest, one at a time | Complete each issue before starting next | | Batched | Related issues in same module | Group by area, address together | | Parallel | Independent issues | Spawn focused subagents (respects context budget) |

Sequential is the default. Use --strategy batched or --strategy parallel to override.

Cycle Limits and Escalation

• Max cycles per issue: Configurable via --max-cycles (default: 6)
• On max cycles reached: Post escalation comment and move to next issue
• Escalation comment format:

**AL CYCLE #6 – Escalation**

### Status
Unable to fully resolve this issue within 6 cycles.

### What Was Accomplished
- [List of completed work]

### Remaining Blockers
- [What prevented resolution]

### Recommendation
[Specific guidance for human to unblock]

---
*Automated by AIWG Al — human intervention recommended*

Provider Configuration

Gitea (via MCP tools)

Uses mcp__gitea__* tools for:

• mcp__gitea__list_repo_issues — fetch issues
• mcp__gitea__get_issue_by_index — read issue details
• mcp__gitea__get_issue_comments_by_index — read thread
• mcp__gitea__create_issue_comment — post cycle status
• mcp__gitea__edit_issue — update labels/status

GitHub (via gh CLI)

Uses gh CLI for equivalent operations:

• gh issue list — fetch issues
• gh issue view N — read issue details
• gh issue comment N — post cycle status
• gh issue close N — close resolved issues

Integration Points

| Component | How Used | |-----------|----------| | /ralph | Core loop engine (internal) | | /issue-list | Fetch and filter issues | | /issue-comment | Post cycle status comments | | /issue-close | Close resolved issues | | /issue-sync | Link commits to issues | | mcp__gitea__* | Gitea API access |

Safety and Guardrails

1. Never force-push or make destructive git changes
2. Always run tests before posting completion status
3. Respect --max-cycles — don't loop forever
4. In --interactive mode — pause between issues for human go/no-go
5. Thread scanning is mandatory — never ignore human comments
6. Post status every cycle — the human must be able to see what's happening
7. On error — post blocker comment, don't silently fail

Completion Criteria (per issue)

completion:
  required:
    - implementation_complete: true
    - tests_pass: true
    - thread_feedback_addressed: true
  optional:
    - documentation_updated: if_applicable
    - pr_created: if_branch_per_issue
    - issue_closed: if_interactive_approved

Examples

Address specific issues

/address-issues 17 18 19

Address all open bugs

/address-issues --filter "status:open label:bug"

Interactive mode with branch per issue

/address-issues 17 --interactive --branch-per-issue --max-cycles 8

Address all open issues

/address-issues --all-open --max-cycles 4

With guidance

/address-issues --all-open --guidance "Focus on security bugs, skip feature requests"

Interactive discovery

/address-issues --interactive

Guidance with specific issues

/address-issues 17 18 19 --guidance "These are all related to the auth refactor, address them as a batch"

Composition

This skill orchestrates the following corpus skills per issue:

/address-issues 17 18 19
    │
    ├── For each issue:
    │   ├── issue-list    — fetch issue details and comments
    │   ├── ralph         — execute work loop
    │   │   ├── Cycle N: do work
    │   │   │   └── issue-comment — post structured status to thread
    │   │   ├── scan thread for feedback (incorporate next cycle)
    │   │   └── repeat until resolved or max-cycles reached
    │   ├── issue-sync    — link commits to issue
    │   └── issue-close   — close if resolved
    └── aggregate report

References

• @$AIWG_ROOT/agentic/code/addons/ralph/skills/ralph/SKILL.md — Agent loop engine
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/issue-list/SKILL.md — Fetch and filter issues
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/issue-comment/SKILL.md — Post structured cycle status comments
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/issue-close/SKILL.md — Close resolved issues
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/issue-sync/SKILL.md — Link commits to issues
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/issue-driven-al/SKILL.md — Issue-thread agent loop pattern
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/context-budget.md — Parallel subagent limits