# GitHub Issue Auto-linking in Spec Creation

**Completed**: 2026-01-21
**Branch**: 040-spec-github-linking
**Priority**: P2

## Overview

Automatically link specifications to GitHub epics during the `/doit.specit` workflow. This feature enables bidirectional traceability between roadmap items and GitHub issues.

## Features

### Fuzzy Roadmap Matching

When creating a new spec, the system automatically searches for matching roadmap items:

- Uses fuzzy string matching with 80% similarity threshold
- Matches spec names against roadmap item titles
- Suggests potential matches for user confirmation

### Bidirectional Linking

- **Spec to Epic**: Spec files include GitHub issue reference in frontmatter
- **Epic to Spec**: GitHub epic body updated with spec file path

### Epic Creation Workflow

If no matching epic exists:

1. System prompts to create a new GitHub epic
2. Priority labels propagated from roadmap item
3. Epic description auto-generated from spec summary
4. Feature branch reference included in epic body

## Usage

The linking happens automatically during `/doit.specit`:

```markdown
/doit.specit Build user authentication with OAuth support
```

The system will:
1. Check roadmap for "user authentication" items
2. Find matching epic or offer to create one
3. Update spec.md with `github_epic: #XXX`
4. Update epic body with spec file path

## Requirements Implemented

| ID | Description | Status |
|----|-------------|--------|
| FR-001 | Fuzzy match specs to roadmap items | Done |
| FR-002 | Auto-link to existing GitHub epics | Done |
| FR-003 | Interactive epic creation workflow | Done |
| FR-004 | Bidirectional spec-epic linking | Done |
| FR-005 | Priority label propagation | Done |

## Testing

- 124 tests covering all linking scenarios
- Integration tests for GitHub API interactions
- Fuzzy matching threshold validation

## Related Features

- [GitHub Roadmap Sync](./039-github-roadmap-sync.md)
- [GitHub Milestone Generation](./041-milestone-generation.md)

---

Generated by `/doit.checkin` on 2026-01-21
