issue-context-review

name	issue-context-review
enabled	true
description	Enrich code reviews with business context by finding the linked issue/ticket from branch name or PR/MR description. Validates that code changes satisfy acceptance criteria and business requirements before reviewing.
required_connections	[]
config_fields	[{"key":"issue_tracker","label":"Issue Tracker","required":true,"placeholder":"e.g., gitlab, github, jira, bitbucket"},{"key":"project_key","label":"Project Key (Jira) or Project Path (GitLab/GitHub/Bitbucket)","required":false,"placeholder":"e.g., OPS or team/repo-name"}]
features	["CODE_REVIEW"]

Issue-Context Code Review

Enrich code reviews with business context by resolving linked issues/tickets before the review begins. Ensures code changes satisfy acceptance criteria and business requirements — not just code quality.

Prerequisites

Before executing this skill, ensure:

1. A code review is in progress with access to the PR/MR metadata (branch name, title, description)
2. The relevant issue tracker is accessible via the configured connection
3. The {{config.issue_tracker}} connection is available

Workflow

Step 1: Extract Issue References

Parse the branch name, PR/MR title, and PR/MR description to find issue references.

Branch name patterns:

Pattern	Example	Extracted Reference
{type}/{KEY}-{number}-*	feature/OPS-1234-add-auth	OPS-1234
{type}/{number}-*	fix/1234-null-check	#1234
{type}/#{number}	bugfix/#567	#567
{KEY}-{number}	PROJ-99	PROJ-99
{type}/{KEY}_{number}_*	feature/OPS_1234_add_auth	OPS-1234

PR/MR description patterns:

Pattern	Example	Tracker
{KEY}-{number}	Fixes OPS-1234	Jira
#{number}	Closes #456	GitLab / GitHub
Closes/Fixes/Resolves #{number}	Resolves #789	GitLab / GitHub
Jira URL	https://myorg.atlassian.net/browse/OPS-1234	Jira
GitLab/GitHub issue URL	https://gitlab.com/team/repo/-/issues/456	GitLab / GitHub

Extraction priority:

1. PR/MR description (most explicit signal)
2. PR/MR title
3. Branch name

If no issue reference is found from any source, skip this skill entirely and proceed with the standard code review. Do not fabricate or guess issue references.

Step 2: Fetch Issue Details

Based on {{config.issue_tracker}}, fetch the issue details:

GitLab:

source ./_skills/connections/gitlab/gitlab/scripts/gitlab_helpers.sh
ISSUE=$(gitlab_get_issue "{{config.project_key}}" $ISSUE_NUMBER)

GitHub:

source ./_skills/connections/github/github/scripts/github_helpers.sh
ISSUE=$(gh issue view $ISSUE_NUMBER --repo "{{config.project_key}}" --json title,body,labels,state,assignees)

Jira:

source ./_skills/connections/atlassian/jira/scripts/jira_helpers.sh
ISSUE=$(jira_get_issue "{{config.project_key}}-${ISSUE_NUMBER}")

Bitbucket:

source ./_skills/connections/bitbucket/bitbucket/scripts/bitbucket_helpers.sh
ISSUE=$(bitbucket_get_issue "{{config.project_key}}" $ISSUE_NUMBER)

Extract from the fetched issue:

Field	Required	Notes
Title	Yes	Issue summary
Description / Body	Yes	Full requirement description
Acceptance Criteria	If present	Checklist or bullet points defining "done"
Labels / Type	If present	Bug, Feature, Story, Task
Priority	If present	Helps weight review severity
Status	If present	Verify issue is not already closed/done

Step 3: Build Business Context Summary

Compile a structured context block for the code review agent:

## Linked Issue Context

**Issue:** {tracker_prefix}{issue_number} — {issue_title}
**Tracker:** {{config.issue_tracker}}
**Status:** {issue_status}
**Type:** {issue_type}

### Requirements
{issue_description_or_body}

### Acceptance Criteria
{extracted_acceptance_criteria_as_checklist}

Step 4: Inject Context into Review

Provide the business context to the code review with these instructions:

1. Requirements coverage — Verify that the code changes address the requirements described in the linked issue
2. Acceptance criteria — Check each acceptance criterion against the diff. Flag any that appear unmet
3. Scope alignment — Flag changes that appear unrelated to the issue (scope creep) or requirements that are not addressed by any changed file
4. Edge cases from requirements — If the issue describes specific scenarios or constraints, verify the code handles them

Step 5: Append Findings to Review

Add a dedicated section to the review output:

### Business Logic Validation

**Linked Issue:** {tracker_prefix}{issue_number} — {issue_title}

#### Acceptance Criteria Coverage
- [x] {criterion_1} — Addressed in `{file}:{line}`
- [ ] {criterion_2} — **Not addressed in this PR/MR**
- [x] {criterion_3} — Addressed in `{file}:{line}`

#### Observations
- {any scope misalignment, missing requirements, or partial implementations}

Skip Conditions

Do NOT execute this skill when:

• No issue reference is found in the branch name, PR/MR title, or PR/MR description
• The referenced issue cannot be fetched (tracker unreachable, permission denied, issue not found)
• The issue is in a terminal state (Closed, Done, Cancelled) and appears stale

When skipping, silently proceed with standard code review. Do not post warnings about missing issue references.

Output

When this skill executes successfully, the code review output includes:

1. The linked issue reference and title
2. Acceptance criteria coverage checklist (met vs. unmet)
3. Scope alignment observations
4. Any business logic concerns found during review

Error Handling

Scenario	Action
No issue reference found	Skip silently, proceed with standard review
Issue not found in tracker	Skip silently, proceed with standard review
Tracker connection unavailable	Skip silently, log warning, proceed with standard review
Issue found but has no acceptance criteria	Include issue title and description as context, note absence of formal criteria
Multiple issue references found	Use the first valid reference; mention others in the review context

Branch Name Parsing Rules

Apply patterns in this order (first match wins):

1. Jira-style key: /([A-Z][A-Z0-9_]+-\d+)/ → e.g., OPS-1234
2. Hash-prefixed number: /#(\d+)/ or /\b#(\d+)\b/ → e.g., #456
3. Bare number after slash: /\/(\d+)[-_]/ → e.g., /1234-fix-bug
4. Bare number in description: /(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#?(\d+)/i

Guidelines

• Never block a review because an issue reference is missing — this is an enrichment, not a gate
• Keep the business context section concise — summarize long issue descriptions
• Do not repeat the entire issue body verbatim; extract the actionable requirements
• When acceptance criteria are informal (prose instead of checklist), convert them to checkable items
• If the issue has subtasks or child tickets, only reference the directly linked issue

Counter-Rationalizations

Shortcut	Counter	Why
"We can skip some steps for this case"	Adapt the workflow steps, don't skip them	Skipped steps are where incidents and oversights originate
"The user seems to already know what to do"	Complete all workflow phases with the user	The workflow catches blind spots that experience alone misses
"This is a minor case, full process is overkill"	Scale the process down, don't turn it off	Minor cases become major when unstructured; the process scales, not disappears
"I'll fill in the details later"	Complete each section before moving on	Deferred details are forgotten; real-time capture is more accurate
"The template output isn't necessary"	Always produce the structured output format	Structured output enables comparison, audit trails, and handoff to other teams