issue-to-merge-request · diff

v1.0.0 to v1.0.0

16 added, 0 removed. Audit B to B.

---

id: issue-to-merge-request

version: "1.0.0"

title: "Issue to Merge Request Workflow"

type: workflow

description: "Complete development workflow from issue analysis to merged PR"

status: experimental

owners:

- "@GSA-TTS/agentic-coding-team"

primary_personas:

- developers

requires:

anchors: []

skills:

- implementation-plan

- test-generation

- secure-code-review

output:

format: markdown

contract:

required_sections:

- "Summary"

- "Outcome"

prohibited_content:

- "Secrets"

- "Real PII"

- "Real CUI"

- "Internal URLs"

categories:

- "development"

- "review"

- "testing"

quality_gates:

readability_max_grade: 10

citations_required: false

triggers:

- "full workflow"

- "issue to PR"

- "development cycle"

- "feature development"

tags:

- "workflow"

- "development"

- "pr"

- "git"

+ collection: engineering

+ routing:

+ task_types:

+ - "orchestrate"

+ - "author"

+ - "test"

+ input_artifacts:

+ - "artifact-brief"

+ output_artifacts:

+ - "pull-request-diff"

+ - "source-code"

+ aliases:

+ - "issue to pr"

+ - "dev cycle"

+ - "feature workflow"

---

# Workflow: Issue to Merge Request

Complete development workflow from analyzing an issue through implementation, testing, and creating a merge request.

## When to Use

- Starting work on a new feature or bug fix

- Need structured approach to development

- Want consistent workflow across team

- Ensuring nothing is missed before PR

## Overview

```

Issue Analysis → Planning → Implementation → Testing → PR → Review → Merge

```

This workflow takes you from an issue description to a merged pull request with confidence that all quality checks pass.

## Prerequisites

- Access to issue tracker (GitHub, GitLab, etc.)

- Repository write access

- Development environment set up

- Tests can run locally

## Workflow Steps

### Step 1: Issue Analysis

**Goal:** Understand requirements and acceptance criteria

**Actions:**

1. Read issue thoroughly

2. Identify acceptance criteria

3. Clarify unknowns with issue author

4. Verify issue is ready for work

**Outputs:**

- Clear understanding of requirements

- List of acceptance criteria

- Any assumptions documented

**Verification:**

- [ ] Requirements understood

- [ ] Acceptance criteria identified

- [ ] No blocking unknowns

- [ ] Issue assigned to you

**Related patterns:** N/A

---

### Step 2: Planning

**Goal:** Break work into implementable tasks

**Actions:**

1. Use [implementation-plan prompt](../../prompts/planning/implementation-plan/SKILL.md)

2. Break feature into tasks (T1, T2, T3...)

3. Identify dependencies between tasks

4. Estimate complexity per task

**Outputs:**

- Implementation plan with tasks

- Dependency graph

- Risk assessment

**Verification:**

- [ ] Tasks are granular (1-4 hours each)

- [ ] Dependencies mapped

- [ ] Risks identified

- [ ] Plan reviewed (if complex)

**Related patterns:** [implementation-plan](../../prompts/planning/implementation-plan/SKILL.md)

---

### Step 3: Create Branch

**Goal:** Isolate work in feature branch

**Actions:**

```bash

# Update main branch

git checkout main

git pull origin main

# Create feature branch

git checkout -b feature/issue-123-brief-description

# Verify branch

git branch --show-current

```

**Outputs:**

- Feature branch created

- Branch name follows convention

**Verification:**

- [ ] Branch created from latest main

- [ ] Branch name descriptive

- [ ] No uncommitted changes from main

---

### Step 4: Implementation

**Goal:** Implement tasks according to plan

**Actions:**

1. Work through tasks in dependency order

2. Make small, focused commits

3. Run tests after each task

4. Keep changes reviewable

**For each task:**

```bash

# Implement task

[write code]

# Run tests

make test

# Commit

git add [files]

git commit -m "feat: brief description

Detailed explanation of changes.

Implements task TX from plan."

```

**Outputs:**

- Code implementing requirements

- Tests for new functionality

- Clear commit history

**Verification:**

- [ ] All planned tasks implemented

- [ ] Tests pass locally

- [ ] Code follows style guide

- [ ] No debugging code left in

**Related patterns:** [test-generation](../../skills/test-generation/SKILL.md)

---

### Step 5: Testing

**Goal:** Verify implementation works correctly

**Actions:**

1. Run full test suite

2. Test happy path manually

3. Test error cases

4. Check test coverage

```bash

# Run all tests

make test

# Check coverage

make coverage

# Manual testing

[test in browser/CLI]

```

**Outputs:**

- All tests passing

- Coverage adequate (>80% for new code)

- Manual testing results

**Verification:**

- [ ] All tests pass

- [ ] New tests added for new functionality

- [ ] Coverage acceptable

- [ ] Manual testing successful

**Related patterns:** [test-generation](../../skills/test-generation/SKILL.md)

---

### Step 6: Security Review

**Goal:** Verify no security issues introduced

**Actions:**

1. Review code against [secure-code-review checklist](../../skills/secure-code-review/SKILL.md)

2. Check for injection vulnerabilities

3. Verify authentication/authorization

4. Scan dependencies

```bash

# Run security linter (example)

bandit -r .

# Check dependencies

npm audit # or pip-audit, cargo audit, etc.

```

**Outputs:**

- Security review completed

- No critical vulnerabilities

**Verification:**

- [ ] Security review done

- [ ] No SQL/command injection

- [ ] No XSS vulnerabilities

- [ ] Dependencies secure

**Related patterns:** [secure-code-review](../../skills/secure-code-review/SKILL.md), [dependency-analysis](../../skills/dependency-analysis/SKILL.md)

---

### Step 7: Prepare PR

**Goal:** Create comprehensive PR description

**Actions:**

1. Push branch to remote

2. Create PR with complete description

3. Add reviewers

4. Link to original issue

```bash

# Push branch

git push origin feature/issue-123-brief-description

# Create PR (via gh CLI or web UI)

gh pr create --title "feat: Brief description" --body "See template"

```

**PR Description Template:**

```markdown

## Summary

[Brief description of changes]

## Related Issue

Closes #123

## Changes Made

- Change 1

- Change 2

- Change 3

## Testing

- [ ] Unit tests added/updated

- [ ] Manual testing completed

- [ ] All tests pass

## Security

- [ ] Security review completed

- [ ] No sensitive data in code

- [ ] Dependencies scanned

## Screenshots (if UI changes)

[Add screenshots]

## Checklist

- [ ] Code follows style guide

- [ ] Tests pass

- [ ] Documentation updated

- [ ] No breaking changes (or documented)

```

**Outputs:**

- PR created

- Description complete

- Reviewers assigned

**Verification:**

- [ ] PR title descriptive

- [ ] Description complete

- [ ] Issue linked

- [ ] CI checks triggered

---

### Step 8: Address Review Feedback

**Goal:** Incorporate reviewer suggestions

**Actions:**

1. Read review comments

2. Respond to questions

3. Make requested changes

4. Push updates

```bash

# Make changes based on feedback

[edit files]

# Commit changes

git add [files]

git commit -m "fix: address review feedback

- Changed X based on @reviewer comment

- Fixed Y as suggested"

# Push updates

git push origin feature/issue-123-brief-description

```

**Outputs:**

- Review feedback addressed

- Discussion resolved

- Tests still passing

**Verification:**

- [ ] All comments addressed

- [ ] Changes explained in responses

- [ ] Tests still pass

- [ ] CI green

---

### Step 9: Merge

**Goal:** Integrate changes into main branch

**Actions:**

1. Wait for approval

2. Ensure CI passes

3. Resolve any conflicts

4. Merge PR

**Outputs:**

- PR merged

- Feature branch can be deleted

**Verification:**

- [ ] Approved by required reviewers

- [ ] CI passing

- [ ] No conflicts

- [ ] Merged successfully

---

## Complete Workflow Checklist

Use this to track progress:

- [ ] Issue analyzed and understood

- [ ] Implementation plan created

- [ ] Feature branch created

- [ ] Code implemented

- [ ] Tests written and passing

- [ ] Security review completed

- [ ] PR created with description

- [ ] Review feedback addressed

- [ ] CI passing

- [ ] PR merged

## Example Walkthrough

### Scenario

**Issue #45**: Add password strength indicator to registration form

### Execution

**Step 1: Issue Analysis**

- Requirement: Visual indicator showing password strength

- Acceptance criteria: Shows weak/medium/strong, updates in real-time

- Assumptions: Use existing validation library

**Step 2: Planning**

- T1: Add password strength calculation (Simple)

- T2: Add UI indicator component (Medium)

- T3: Connect component to input (Simple)

- T4: Add tests (Medium)

- T5: Update documentation (Simple)

**Step 3-4: Implementation**

```bash

git checkout -b feature/issue-45-password-strength

# Implemented T1-T5

git log --oneline

# abc123 docs: update registration guide

# def456 test: add password strength tests

# ghi789 feat: connect strength indicator

# jkl012 feat: add strength indicator component

# mno345 feat: add password strength calculation

```

**Step 5: Testing**

- All 15 tests pass

- Coverage: 95%

- Manual test: indicator updates as expected

**Step 6: Security**

- Password not logged or exposed

- No XSS vulnerabilities in indicator

- Client-side only (server validates separately)

**Step 7: PR Created**

PR #46 created with description, screenshots, checklist

**Step 8-9: Review and Merge**

- Reviewer suggested accessibility improvement

- Added ARIA labels

- Approved and merged

### Outcome

Feature delivered, all tests passing, fully documented

## Common Issues

| Issue | Cause | Solution |

|-------|-------|----------|

| Merge conflicts | Branch out of date | Rebase or merge main regularly |

| CI failures | Tests pass locally but fail in CI | Check environment differences |

| Unclear requirements | Ambiguous issue | Ask for clarification before coding |

| PR too large | Too many changes at once | Break into smaller PRs |

## Exit Criteria

The workflow is complete when:

- [ ] All acceptance criteria met

- [ ] Tests passing in CI

- [ ] Code reviewed and approved

- [ ] PR merged to main

- [ ] Issue closed

- [ ] Documentation updated

## Related Patterns

- [implementation-plan](../../prompts/planning/implementation-plan/SKILL.md) - Planning

- [test-generation](../../skills/test-generation/SKILL.md) - Testing

- [secure-code-review](../../skills/secure-code-review/SKILL.md) - Security

- [qa-round](../qa-round/SKILL.md) - QA workflow

## References

- For git best practices, see your team's contribution guide

- For PR templates, see [GitHub docs](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests)