Commit-to-Issue Traceability Link Prompt

This prompt is designed for compliance-focused engineering teams, platform engineers, and release managers who must prove that every commit in a release is traceable to an approved work item, such as a Jira ticket, GitHub issue, or internal change request. The primary job-to-be-done is automated audit evidence generation: transforming a list of commits and their associated pull request descriptions into a structured traceability matrix that flags orphaned changes. The ideal user is an engineering lead or auditor integrating this check into a CI/CD pipeline or a pre-release governance gate, not a developer casually reviewing their own work.

Use this prompt when your organization operates under regulatory requirements like SOC 2, ISO 27001, or internal change management policies that mandate a documented justification for every production change. It is appropriate for repositories that enforce linking conventions, such as requiring issue keys in branch names or Closes #123 in PR bodies. The prompt requires structured inputs: a list of commit SHAs with messages, their associated PR descriptions, and a configurable regex pattern or format for valid work item references. Do not use this prompt for repositories without any linking convention, for exploratory branches where work items don't yet exist, or for automated dependency bump commits that follow a separate, pre-approved exception path. In those cases, the prompt will produce a high volume of false-positive violations that erode trust in the audit signal.

Before running this prompt, ensure your input data is complete and normalized. The harness should extract commit messages and PR bodies from your git provider's API, not from local clones that may be stale. Define your traceability contract explicitly in the [CONSTRAINTS] placeholder: for example, 'A valid link is a Jira key matching [A-Z]+-[0-9]+ in the PR description or a GitHub issue reference in the commit message footer.' The prompt is not a detective control for fraudulent commits; it only verifies the presence and format of a link, not the semantic validity of the association. After generating the matrix, route any commit flagged as 'UNLINKED' to a human review queue where an engineering manager can either provide the missing link, mark the commit as an approved exception, or block the release. The next step is to wire this prompt into your release pipeline and configure the harness to fail the pipeline only when unlinked commits exceed a defined risk threshold.

The following prompt template is designed to analyze a set of commit messages and pull request descriptions against a known list of issues or work items. It produces a structured traceability matrix that maps each commit to its corresponding issue, flags orphaned changes with no documented link, and identifies issues that lack associated commits. The template uses square-bracket placeholders to make it adaptable to different repository conventions, issue tracking systems, and output formats without rewriting the core instruction.

codeCopy
You are a traceability auditor for a software repository. Your task is to analyze a set of commits and pull request descriptions against a known list of issues or work items, then produce a traceability matrix.

## INPUTS

### Commits and PR Descriptions
[COMMIT_AND_PR_DATA]

### Known Issues or Work Items
[ISSUE_LIST]

### Link Format Convention
[LINK_FORMAT]

## OUTPUT SCHEMA

Return a JSON object with the following structure:

{
  "traceability_matrix": [
    {
      "commit_sha": "string (first 7 characters of commit hash)",
      "commit_message_summary": "string (first line of commit message)",
      "linked_issues": ["string (issue key or work item ID)"],
      "link_evidence": "string (exact text from commit or PR body that establishes the link)",
      "link_confidence": "high|medium|low",
      "link_method": "auto_close_keyword|manual_reference|pr_body_only|inferred_from_branch|none"
    }
  ],
  "orphaned_commits": [
    {
      "commit_sha": "string",
      "commit_message_summary": "string",
      "reason": "string (explanation of why no link was found)",
      "suggested_action": "string (recommendation for remediation)"
    }
  ],
  "unlinked_issues": [
    {
      "issue_key": "string",
      "issue_title": "string",
      "status": "string",
      "risk": "string (explanation of why this issue may lack associated changes)"
    }
  ],
  "summary": {
    "total_commits": "number",
    "total_issues": "number",
    "linked_commits": "number",
    "orphaned_commits": "number",
    "unlinked_issues": "number",
    "traceability_percentage": "number (linked_commits / total_commits * 100)"
  },
  "compliance_flags": [
    {
      "flag": "string (description of a compliance concern)",
      "severity": "high|medium|low",
      "affected_items": ["string (commit SHAs or issue keys)"],
      "remediation": "string (suggested fix)"
    }
  ]
}

## CONSTRAINTS
[CONSTRAINTS]

## EXAMPLES
[EXAMPLES]

## INSTRUCTIONS

1. Parse each commit message and PR description for issue references matching the link format convention.
2. For each commit, determine the link method: auto-close keywords (fixes, closes, resolves), manual references (bare issue keys), PR body-only links, branch name inference, or none.
3. Assign link confidence: high for explicit auto-close keywords, medium for manual references in commit body, low for branch name inference or PR-only links.
4. Flag any commit with no detectable issue link as orphaned. Provide a specific reason and suggested remediation.
5. Cross-reference the issue list against linked issues to identify issues with no associated commits.
6. Generate compliance flags for: missing links on high-risk changes, inconsistent link formats, issues closed without commits, and commits referencing closed or invalid issues.
7. If [RISK_LEVEL] is "high", require explicit human verification of all orphaned commits and unlinked issues before finalizing.

To adapt this template, replace each square-bracket placeholder with concrete data and configuration. The [COMMIT_AND_PR_DATA] placeholder should contain the full commit messages, SHAs, and associated PR descriptions in a structured format. The [ISSUE_LIST] should include issue keys, titles, and current status from your tracking system. The [LINK_FORMAT] placeholder defines the regex or pattern your team uses to reference issues, such as PROJ-\\d+ for Jira-style keys or #\\d+ for GitHub issues. The [CONSTRAINTS] section can specify additional rules like required footer formats, branch naming conventions, or compliance standards. The [EXAMPLES] section should include 2-3 annotated examples of correctly linked and orphaned commits to calibrate the model's behavior. The [RISK_LEVEL] placeholder accepts "low", "medium", or "high" to control whether human review gates are required in the output.

Before deploying this prompt in a production harness, validate that the output JSON matches the schema exactly. Common failure modes include the model inventing issue keys not present in the input, misclassifying branch name patterns as issue references, or failing to detect auto-close keywords when they appear in non-standard positions within the commit body. Test the prompt against a golden dataset of commits with known link status, and measure precision and recall on orphaned commit detection. For compliance workflows, always route outputs flagged with severity: high to a human review queue before the matrix is considered final.

This prompt is designed to run as a gate in a CI/CD pipeline or as a pre-receive hook, not as a one-off manual check. The harness must capture the commit message, the PR description (if available), and the linked issue references, then pass them into the prompt as structured inputs. The model returns a traceability matrix with a missing_links array; the harness should parse this JSON output and fail the pipeline if any commits lack a valid issue reference or if the confidence score for any link falls below a configurable threshold (default 0.85).

Wire the prompt into a GitHub Actions workflow, a GitLab CI job, or a pre-receive hook script. The harness should: (1) extract the commit range or PR diff using git log --format='%H %s %b' and the PR body from the API; (2) call the model with the prompt template, passing [COMMIT_MESSAGES], [PR_DESCRIPTION], and [ISSUE_REGEX_PATTERN] (e.g., [A-Z]+-\d+ for Jira-style keys); (3) parse the JSON response and validate the schema—every entry in traceability_matrix must have commit_hash, linked_issues, and confidence fields; (4) if missing_links is non-empty or any confidence is below threshold, post a structured comment on the PR and set a failing status check. Implement retry logic with exponential backoff (3 attempts max) for model API failures, and log every prompt-response pair to an audit bucket (S3 or equivalent) for compliance review.

For high-assurance audit workflows, add a human approval step: if the harness detects orphaned commits or low-confidence links, it should create a review task in your ticketing system rather than blocking the merge outright. The prompt's [RISK_LEVEL] input can be set to high to instruct the model to flag ambiguous references for human review. Avoid running this prompt on every push without caching—use the commit hash as a cache key to avoid re-processing unchanged commits. The harness should also validate that the model's output conforms to the expected JSON schema before acting on it; schema validation failures should trigger a retry with a stricter [OUTPUT_SCHEMA] constraint appended to the prompt.