cross-repo-issues

name	cross-repo-issues
description	Use when a bug or feature request belongs in an upstream, parent, or dependency repository rather than the current one. Guides detection, mapping, and safe cross-repo issue creation with user confirmation.

Cross-Repo Issue Creation

Overview

Not every issue belongs in the repository where it was discovered. Bugs in forked code belong upstream. Problems in a monorepo dependency belong in that dependency's repo. Filing issues in the wrong place wastes maintainer time and delays fixes.

Core principle: ALWAYS confirm the target repository with the user before creating an issue elsewhere. Never auto-create issues in repositories you don't own.

Iron Law:

NO CROSS-REPO ISSUE CREATION WITHOUT EXPLICIT USER CONFIRMATION

When to Use

• Bug discovered in forked code that should be reported upstream
• Issue in a monorepo sub-package that belongs in the package's source repo
• Bug in a third-party dependency that should be filed in the library's repo
• Feature request that affects an upstream project
• Security vulnerability that needs to be reported to the upstream maintainer

Use this ESPECIALLY when:

• Working in a fork and the bug exists in the original repo
• A monorepo package wraps an external library and the bug is in the library
• You need to coordinate fixes across multiple repositories

When NOT to Use

• Issue is local to the current repository (use normal issue workflow)
• You don't have access to the target repository
• The upstream project is archived or unmaintained
• Simple configuration issues that are project-specific

Configuration

Add upstreamRepos to your codingbuddy.config.json:

{
  "upstreamRepos": {
    ".": "original-owner/original-repo",
    "packages/ui": "design-system/ui-kit",
    "dep:react": "facebook/react"
  }
}

Key Conventions

Key Pattern	Meaning	Example
"."	Current repo is a fork of this upstream	"original-owner/repo"
"packages/..."	Monorepo package maps to external repo	"org/package-repo"
"dep:<name>"	npm/pip dependency maps to its source repo	"facebook/react"

Minimal Configuration

For a simple fork, only one entry is needed:

{
  "upstreamRepos": {
    ".": "upstream-owner/upstream-repo"
  }
}

The Three Phases

Phase 1: Detect — Identify Where the Issue Belongs

Determine if the issue should go to another repository:

1. Check the code origin

   • Is the buggy code from an upstream repo? (git log --follow <file>)
   • Is it in a vendored or forked dependency?
   • Does git remote -v show an upstream remote?

2. Check the config mapping

   • Read upstreamRepos from codingbuddy.config.json
   • Match the affected file path or package name to a mapping key
   • If no mapping exists, ask the user for the target repo

3. Verify the issue doesn't already exist upstream

   • Search upstream issues: gh issue list -R <upstream> --search "<keywords>"
   • Check for duplicates before creating

Decision matrix:

Scenario	Target Repo	Key
Bug in forked code	Upstream repo	"."
Bug in monorepo sub-package's upstream	Package source repo	"packages/<name>"
Bug in third-party dependency	Library repo	"dep:<package>"
Bug in your own code	Current repo (stop here)	N/A

Completion criteria:

• Target repository identified
• Duplicate check completed
• Issue is confirmed to belong upstream

Phase 2: Confirm — Get User Approval

MANDATORY: Never skip this phase.

Present the following to the user before proceeding:

Cross-Repo Issue Detected:
  Source:  <current-repo> (<file-or-package>)
  Target:  <upstream-repo>
  Reason:  <why this belongs upstream>
  Title:   <proposed issue title>

Proceed with creating issue in <upstream-repo>? (y/n)

Include in the confirmation:

• The exact target repository (owner/repo)
• Why the issue belongs there (not here)
• Proposed issue title and summary
• Whether user has write access to the target repo

If user declines:

• Offer to create the issue in the current repo instead
• Add a label like upstream or external-dependency for tracking

Completion criteria:

• User explicitly confirmed target repo
• User approved issue title and content

Phase 3: Create — File the Issue

Create the issue in the confirmed target repository:

1. Format the issue body

## Description

<Clear description of the issue>

## Reproduction

- Repository: <your-repo> (discovered while working on <context>)
- File/Package: <affected file or package>
- Steps to reproduce: <steps>

## Expected Behavior

<what should happen>

## Actual Behavior

<what actually happens>

## Environment

- Version: <upstream version in use>
- OS: <if relevant>

## Additional Context

Discovered in downstream repo: <your-repo-url>

1. Create the issue

gh issue create -R <owner/repo> \
  --title "<title>" \
  --body "<body>"

1. Link back to current repo (optional)
   • Create a tracking issue in current repo referencing the upstream issue
   • Add label: blocked-upstream or waiting-upstream

gh issue create \
  --title "Tracking: <upstream-owner/repo>#<number>" \
  --body "Upstream issue: <url>\nBlocked until upstream fix is available." \
  --label "blocked-upstream"

Completion criteria:

• Issue created in target repository
• Issue URL shared with user
• (Optional) Tracking issue created in current repo

Quick Reference

Phase	Action	Verification
1. Detect	Identify target repo from config or code origin	Target repo confirmed
2. Confirm	Present plan to user, get explicit approval	User said yes
3. Create	File issue via gh, link back if needed	Issue URL available

Safety Checklist

Before creating any cross-repo issue:

• Target repo is correct (double-check owner/repo)
• Issue doesn't already exist upstream (searched)
• User explicitly approved the creation
• Issue body is professional and includes reproduction steps
• No sensitive/proprietary information in the issue body
• You have access to create issues in the target repo

Red Flags — STOP

Thought	Reality
"I'll just create it, the user won't mind"	STOP. Always confirm. Cross-repo actions are visible to external maintainers.
"It's obviously an upstream bug"	Maybe. But confirm the target repo with the user first.
"I'll skip the duplicate check"	Duplicate issues waste maintainer time and hurt your credibility.
"The config mapping is enough confirmation"	Config maps repos, but the user must confirm each issue creation.
"I'll include our internal details for context"	STOP. Review for sensitive information before posting to external repos.
"No config? I'll guess the upstream repo"	Ask the user. Wrong repo = noise for unrelated maintainers.

Examples

Fork → Upstream

Config: { "upstreamRepos": { ".": "expressjs/express" } }

Detected: Bug in request parsing (inherited from upstream)
Target:   expressjs/express
Action:   Confirm with user → Create issue in expressjs/express

Monorepo Package → Source Repo

Config: { "upstreamRepos": { "packages/icons": "design-org/icon-library" } }

Detected: Missing icon in packages/icons (sourced from design-org/icon-library)
Target:   design-org/icon-library
Action:   Confirm with user → Create issue in design-org/icon-library

Dependency → Library Repo

Config: { "upstreamRepos": { "dep:zod": "colinhacks/zod" } }

Detected: Validation bug in zod usage
Target:   colinhacks/zod
Action:   Confirm with user → Search existing issues → Create if new