issue-auto-sync

What this skill does

# issue-auto-sync

Automatically detect and update linked issues after commits or artifact changes.

## Triggers


Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

- "link commits to issues" → commit-to-issue tracing
- "auto-close issues" → issue auto-closure on commit

## Purpose

This skill maintains issue tracker synchronization by:
- Detecting issue references in commit messages
- Scanning AIWG artifacts for issue mentions
- Automatically updating issues with progress
- Closing issues when work is completed
- Notifying blocked/dependent issues

## Behavior

When triggered, this skill:

1. **Detects issue references**:
   - Parse recent commit messages for patterns like "Fixes #123", "Addresses #45"
   - Scan AIWG artifacts for issue mentions in metadata or references sections
   - Check code comments for TODO(#123) or @issue #123 patterns

2. **Classifies reference type**:
   - **Completion**: `Fixes`, `Closes`, `Resolves` → Close issue
   - **Progress**: `Implements`, `Addresses`, `Part of` → Add progress comment
   - **Reference**: `Refs`, `See`, `Related to` → Add reference comment
   - **Blocker**: `Blocks`, `Blocked by` → Add blocker notification

3. **Gathers context**:
   - Extract commit SHA, message, author, timestamp
   - List changed files and line counts
   - Find related artifacts and test files
   - Check CI/CD status if available

4. **Generates appropriate comment**:
   - Use `task-completed.md` template for closure
   - Use `progress-update.md` template for progress
   - Use `blocker-found.md` template for blockers
   - Include commit details, file changes, and context

5. **Updates issues via API**:
   - Post comment to GitHub (using `gh` CLI) or Gitea (using MCP tools)
   - Close issue if completion pattern detected
   - Add appropriate labels (in-progress, blocked, completed)
   - Update dependent/blocking issues

6. **Reports results**:
   - List issues detected and updated
   - Show actions taken (commented, closed, labeled)
   - Highlight any errors or skipped updates

## Reference Detection Patterns

### Commit Message Patterns

| Pattern | Action | Example |
|---------|--------|---------|
| `Fixes #N` | Close issue | `git commit -m "Fixes #17: Add auth"` |
| `Closes #N` | Close issue | `git commit -m "Closes #17"` |
| `Resolves #N` | Close issue | `git commit -m "Resolves #17"` |
| `Implements #N` | Progress update | `git commit -m "Implements #17 partially"` |
| `Addresses #N` | Progress update | `git commit -m "Addresses #17"` |
| `Part of #N` | Progress update | `git commit -m "Part of #17"` |
| `Related to #N` | Reference comment | `git commit -m "Related to #17"` |
| `Refs #N` | Reference comment | `git commit -m "Refs #17"` |
| `See #N` | Reference comment | `git commit -m "See #17"` |
| `Blocks #N` | Blocker notification | `git commit -m "Blocks #17"` |
| `Blocked by #N` | Blocker notification | `git commit -m "Blocked by #17"` |

**Multi-issue support**:
```bash
git commit -m "Fixes #17, Closes #18, Addresses #19"
```
Each issue is processed separately.

**Cross-repository**:
```bash
git commit -m "Fixes owner/repo#123"
```
Updates issue in the specified repository.

### Artifact Reference Patterns

**Metadata section**:
```markdown
## References

- Primary issue: #17
- Related: #18, #19
- Blocks: #20
```

**Frontmatter**:
```yaml
---
issue: 17
related_issues: [18, 19]
blocked_by: 16
---
```

**Inline mentions**:
```markdown
This feature addresses issue #17 by implementing automatic synchronization.
```

### Code Reference Patterns

**TODO comments**:
```typescript
// TODO(#17): Add retry logic
// FIXME(#17): Handle edge case
```

**Documentation comments**:
```typescript
/**
 * @issue #17
 * @implements @.aiwg/requirements/UC-017.md
 */
export class IssueSync {}
```

**Test descriptions**:
```typescript
describe('Issue #17: Auto-sync', () => {
  it('should detect issue references', () => {});
});
```

## Context Gathering

For each detected issue, collect:

**Commit Information**:
- SHA (short and full)
- Message (full text)
- Author name and email
- Timestamp
- Branch name
- Parent commit(s)

**Change Statistics**:
- Files changed (count)
- Lines added
- Lines removed
- Key files (categorize as code, test, docs, config)

**Artifact Context**:
- Path to artifact
- Artifact type (requirements, architecture, test plan, etc.)
- Section where issue is mentioned
- Related artifacts

**Build/Test Context**:
- CI/CD pipeline status (if available)
- Test results (passing/failing)
- Code coverage changes

## Comment Generation

### Completion Comment (Fixes/Closes/Resolves)

```markdown
## Task Completed

**Status**: Completed
**Completed by**: {author_name}
**Completion date**: {commit_timestamp}

## Summary of Work

{commit_message}

## Changes Made

### Files Modified
{list_of_changed_files_with_categorization}

**Code Changes**:
- `{file_path}` (+{lines} -{lines})

**Tests Added**:
- `{test_file_path}` (+{lines} -{lines})

**Documentation**:
- `{doc_file_path}` (+{lines} -{lines})

### Statistics
- Total files changed: {count}
- Lines added: {count}
- Lines removed: {count}

## Commit Details

- **Commit**: {repo}@{short_sha}
- **Branch**: {branch_name}
- **Full SHA**: {full_sha}
- **View**: {commit_url}

## Verification

- [x] Code committed and pushed
- [ ] CI/CD pipeline (check: {ci_url})
- [ ] Code review (if required)
- [ ] Ready for deployment

## Related Items

- Commit: {repo}@{sha}
{if_applicable}
- Related PR: #{pr_number}
- Related issues: #{issue_numbers}
- Artifacts: {artifact_paths}

---

*Automated completion notice from commit {short_sha}. Please review and verify.*
```

### Progress Comment (Implements/Addresses/Part of)

```markdown
## Progress Update

**Status**: In Progress
**Updated by**: {author_name}
**Update date**: {commit_timestamp}
**Progress**: {estimate}% complete

## Work Completed

{commit_message}

### Changes in This Update

**Files modified**: {count}
{key_file_list}

**Lines changed**: +{added} -{removed}

### Commits in This Update
- {short_sha}: {message}

## Current Status

{infer_from_commit_and_files}

## Commit Reference

- **Commit**: {repo}@{short_sha}
- **Branch**: {branch_name}
- **View**: {commit_url}

---

*Automated progress update from commit {short_sha}.*
```

### Blocker Comment (Blocks/Blocked by)

```markdown
## Blocker Alert

**Status**: Blocked
**Reported by**: {author_name}
**Reported date**: {commit_timestamp}
**Severity**: {infer_from_context}

## Blocker Description

{commit_message}

## Context

Related commit: {repo}@{short_sha}

{additional_context_from_changed_files}

## Impact

{analyze_blocking_relationship}

## Commit Reference

- **Commit**: {repo}@{short_sha}
- **Branch**: {branch_name}
- **View**: {commit_url}

---

*Automated blocker notification from commit {short_sha}. Please address this blocking issue.*
```

## API Integration

### GitHub (via `gh` CLI)

```bash
# Add comment
gh issue comment {issue_number} --body "{comment_body}"

# Close issue
gh issue close {issue_number} --comment "{completion_comment}"

# Add label
gh issue edit {issue_number} --add-label "completed"
```

### Gitea (via MCP tools)

```bash
# Add comment
mcp__gitea__create_issue_comment \
  --owner {owner} \
  --repo {repo} \
  --issue_number {number} \
  --body "{comment_body}"

# Close issue
mcp__gitea__edit_issue \
  --owner {owner} \
  --repo {repo} \
  --issue_number {number} \
  --state closed

# Then add completion comment
```

### Repository Detection

```bash
# Check remotes to determine platform
git remote -v

# If github.com → Use gh CLI
# If git.integrolabs.net or other Gitea → Use MCP tools
# Prefer origin remote if multiple remotes present
```

## Safety and Validation

### Skip Updates If:

- Issue number in URL: `https://example.com/issues/123`
- Issue number is version: `v1.2.3`
- Commit message contains `[skip-issue-sync]`
- Issue doesn't exist
- Issue is already closed (for non-co