Skip to content

docs(problems): add cross-repo work decomposition problem doc - #872

Open
guyoron1 wants to merge 1 commit into
upstream-mainfrom
docs/cross-repo-work-decomposition
Open

docs(problems): add cross-repo work decomposition problem doc#872
guyoron1 wants to merge 1 commit into
upstream-mainfrom
docs/cross-repo-work-decomposition

Conversation

@guyoron1

Copy link
Copy Markdown
Owner

What

Adds docs/problems/cross-repo-work-decomposition.md — a problem doc on how a single unit of intent is split across repositories, who owns the parts, and what makes the parts one thing rather than several unrelated issues.

Why

Cross-repo coordination is referenced as an open question across architecture.md, code-review.md, and codebase-context.md, but has never been written up as one coherent problem.

The doc starts from what already exists rather than claiming a blank slate:

  • Prerequisite issue creation — triage can file blocking issues in other repos, allowlisted via create_issues.allow_targets
  • Independent per-repo discovery — each repo polls with its own filter and no shared state

It then names the four capabilities those primitives do not cover: decomposition, ownership, aggregation, and ordering/atomicity.

Structure

  • Four shapes of cross-repo work (prerequisite chain, parallel slices, atomic contract change, mechanical fan-out) — they do not all need the same solution
  • Three approaches, from "do nothing beyond what exists" through parent-issue coordination to a fullsend-owned work object
  • A worked example from an external Jira-driven orchestrator, included for its visible trade-offs — repository grounding and sizing discipline transfer; its central state store is the model this project has deliberately avoided
  • An explicit section on the tension with the repo as coordinator, since a cross-repo change is precisely the case where no single repo can see the whole change

Problem doc only — it explores and does not decide. If the parent-issue approach turns out to be sufficient for the atomic contract change, the principle survives intact and this becomes a linking convention rather than an architecture change.

🤖 Generated with Claude Code

Names the gap between the cross-repo primitives that exist today
(triage prerequisite issue creation, per-repo independent polling)
and the four capabilities they do not cover: decomposition,
ownership, aggregation, and ordering/atomicity.

Splits cross-repo work into four shapes that need different
solutions, surveys three approaches plus a worked example from an
external implementation, and states the tension with the
repo-as-coordinator principle rather than assuming it away.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant