---
namespace: aiwg
name: issue-auto-sync
platforms: [all]
description: Detect issue references in commits and artifacts and automatically update or close linked tracker issues

---

# 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-completion actions)
- User lacks permission to update issue

### Validate Before Close:

- Issue exists and is currently open
- User has permission to close
- No other open blockers referenced
- CI/CD passing (if configured to check)

### Error Handling:

**Issue not found**:
```
Warning: Issue #123 not found. Skipping update.
```

**Permission denied**:
```
Warning: Cannot update issue #123 - insufficient permissions. Manual update required.
```

**API rate limit**:
```
Warning: API rate limit reached. Queuing updates for retry.
```

## Configuration

### `.aiwg/config.yaml`

```yaml
issue_auto_sync:
  enabled: true
  platforms:
    - github
    - gitea

  # When to run
  triggers:
    post_commit: true
    artifact_update: true
    manual: true

  # Detection patterns
  patterns:
    close: ["Fixes", "Closes", "Resolves"]
    progress: ["Implements", "Addresses", "Part of"]
    reference: ["Refs", "See", "Related to"]
    blocker: ["Blocks", "Blocked by"]

  # Behavior
  auto_close: true
  auto_label: true
  notify_dependencies: true

  # Safety
  skip_patterns:
    - "\\[skip-issue-sync\\]"
    - "https?://.*/issues/\\d+"
    - "v\\d+\\.\\d+\\.\\d+"

  # Scanning
  scan_commits: 1  # Number of commits to scan
  scan_artifacts: true
  scan_code_comments: false  # Disable for performance
```

### Git Hooks Integration

**Post-commit hook** (`.git/hooks/post-commit`):

```bash
#!/bin/bash
# Auto-sync issues after commit

# Check if skill is enabled
if grep -q "issue_auto_sync: enabled: true" .aiwg/config.yaml 2>/dev/null; then
  # Run issue sync skill
  aiwg skill run issue-auto-sync
fi
```

**Pre-push hook** (bulk sync before push):

```bash
#!/bin/bash
# Sync all commits in push

# Get commits being pushed
commits=$(git log origin/main..HEAD --pretty=format:"%H")

# Run sync for each
for commit in $commits; do
  aiwg issue-sync --commit $commit
done
```

## Usage Examples

### After Commit

```bash
# Commit references issue
git commit -m "Fixes #17: Add issue sync automation"
git push

# Skill automatically runs (if post-commit hook enabled)
# Or manually trigger
aiwg skill run issue-auto-sync

Output:
"Issue Auto-Sync Complete

Commits scanned: 1
Issues detected: 1

Updated Issues:
✅ #17 - Closed with completion comment
   Commit: abc123
   Action: Closed issue with task-completed template

No errors."
```

### Scan Recent Commits

```bash
# Scan last 5 commits
aiwg issue-sync --scan-recent 5

Output:
"Issue Auto-Sync Complete

Commits scanned: 5
Issues detected: 3

Updated Issues:
✅ #17 - Closed
✅ #18 - Progress update added
✅ #19 - Reference comment added

Skipped:
⚠️  #20 - Already closed
⚠️  #21 - Issue not found"
```

### Artifact Update Trigger

```markdown
When .aiwg/requirements/UC-017.md is updated with:

## References
- Primary issue: #17
- Related: #18

Skill detects reference and adds comment to #17:
"Referenced in artifact: .aiwg/requirements/UC-017.md
This issue is now documented in requirements."
```

## Integration with Other Skills

### Works With:

- **traceability-check**: Links issues to requirements and code
- **project-awareness**: Understands repository structure
- **artifact-metadata**: Extracts issue references from AIWG artifacts

### Triggers From:

- **git-workflow**: After commit, push, merge
- **artifact-orchestration**: After artifact creation/update
- **sdlc-phase-transitions**: When moving between phases

## Report Format

```markdown
## Issue Auto-Sync Report

**Run time**: {timestamp}
**Trigger**: {post-commit|manual|artifact-update}
**Scope**: {commit_range_or_artifacts}

### Summary

- Commits scanned: {count}
- Artifacts scanned: {count}
- Issues detected: {count}
- Issues updated: {count}
- Errors: {count}

### Actions Taken

#### Closed Issues ({count})
- #17 - "Add issue sync automation"
  - Commit: abc123
  - Comment: task-completed.md
  - Label added: completed

#### Progress Updates ({count})
- #18 - "Update documentation"
  - Commit: def456
  - Comment: progress-update.md
  - Label added: in-progress

#### Reference Comments ({count})
- #19 - "Refactor API"
  - Commit: ghi789
  - Comment: reference

#### Blocker Notifications ({count})
- #20 - "Deploy pipeline"
  - Blocked by: #21
  - Notified in commit jkl012

### Skipped ({count})

- #22 - Already closed
- #23 - Issue not found
- #24 - Permission denied

### Errors ({count})

{if_any}
- API rate limit reached (queued for retry)
- Connection timeout for issue #25

### Next Actions

{if_applicable}
- Review closed issues: #{numbers}
- Address permission issues: #{numbers}
- Retry failed updates: #{numbers}
```

## Best Practices

### Commit Message Conventions

**Clear intent**:
```bash
✅ Good: "Fixes #17: Add automatic issue synchronization"
❌ Bad: "Fixed stuff"
```

**Multiple issues**:
```bash
✅ Good: "Fixes #17, Addresses #18, Related to #19"
❌ Bad: "Fixes 17 18 19" (ambiguous)
```

**Descriptive context**:
```bash
✅ Good: "Implements #17: Add commit message parsing and API integration"
❌ Bad: "Implements #17" (no context)
```

### Artifact References

**Explicit in metadata**:
```markdown
## References

- Primary: #17 - Issue sync automation
- Related: #18 - Documentation updates
- Blocks: #20 - Until API integration complete
```

**Clear in descriptions**:
```markdown
This feature implements issue #17 by adding automatic synchronization
between git commits and issue trackers.
```

## Output Locations

- Sync reports: `.aiwg/reports/issue-sync-{timestamp}.md`
- Error logs: `.aiwg/logs/issue-sync-errors.log`
- Update history: `.aiwg/logs/issue-updates.json`

## References

- Commands: @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/commands/issue-sync.md, @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/commands/issue-close.md
- Templates: @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/templates/issue-comments/
- MCP tools: Gitea issue management


---
Source attribution: jmagly
Original project: https://github.com/jmagly/aiwg/blob/bc0cd4d707708593ef15781cb9d38364ea29bdd5/agentic/code/frameworks/sdlc-complete/skills/issue-auto-sync/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2024 Joe Magly

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: jmagly
Original project: https://github.com/jmagly/aiwg/blob/bc0cd4d707708593ef15781cb9d38364ea29bdd5/agentic/code/frameworks/sdlc-complete/skills/issue-auto-sync/SKILL.md
Attribution basis: Source repository record

Fields of work: Project & Program Management, Sales, Customer Support
Roles: Customer Success Manager, Project Manager, Sales Operations, Sales Development Rep (SDR), Technical Support
Specialties: API, Cross Platform, Git
Tools: GitHub
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 5c7e8a48e1aacd50490e488a3e139ce562b5ac68b73a86eedda768c5c62e1a45