Skip to content

docs(coordinator): link a blocked issue's blockers as dependencies so it leaves triage - #21

Merged
zackees merged 1 commit into
masterfrom
docs/coordinator-blocked-deps
Oct 27, 2026
Merged

zackees merged 1 commit into
masterfrom
docs/coordinator-blocked-deps

Conversation

@zackees

@zackees zackees commented Oct 27, 2026

Copy link
Copy Markdown
Member

Problem

obs-studio#1865's body says "Blocked by #1864 (CEF upgrade) and the Linux sandbox part of #1092". Both are open. Nothing in the tooling read that sentence, so uv run -m workflow.coordinator listed the issue under triage on every tick and each tick posted the same verdict again — five triage comments between 2026-10-23 and 2026-10-27, the last four within 24 hours and two within 40 minutes.

The work list already has the rule for this: issue_task() returns None when item.open_blockers is set, and GhBackend fills it from issueDependenciesSummary { blockedBy }. The issue simply had no dependency links, so the count was 0.

Change

One bullet in the org coordinator skill's §6 (Triage): when the blockers are named in prose, link them in the same tick with the issue-dependency API, before posting the verdict.

  • POST repos/obs-rust/<repo>/issues/<N>/dependencies/blocked_by with issue_id set to the blocker's numeric id (gh api repos/.../issues/<n> --jq .id), not its number.
  • With one open blocker the issue leaves triage and returns by itself when the last blocker closes, so a blocked issue costs one comment instead of one per tick.
  • Names the trap (id vs number) and the churn it prevents, with the instance.

Verified

On obs-studio#1865, after linking both blockers:

  • gh api graphql -f query='{repository(owner:"obs-rust",name:"obs-studio"){issue(number:1865){issueDependenciesSummary{blockedBy}}}}' → {"blockedBy":2}.
  • A fresh uv run -m workflow.coordinator --json no longer contains obs-studio#1865 (it did in the list computed 20 minutes earlier).

Docs only: no code, no labels, no CI change.

Triage re-listed obs-studio#1865 on every tick because its blockers were
named in prose (#1864, #1092) and nothing read them: five triage comments
in four days, each repeating the same verdict. The work list already hides
an issue with an open blocker (issueDependenciesSummary.blockedBy), so the
fix is the link, not another comment.

Records the command, the id-vs-number trap, and the churn it prevents.

@zackees zackees left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed — correct, scoped, and verified.

  • The change is one bullet in .claude/skills/obs-org-coordinator/SKILL.md §6 (Triage), which is exactly where the churn originates: issue_task() returns None only when item.open_blockers is set, and GhBackend fills that from issueDependenciesSummary { blockedBy }, so prose "Blocked by #N" is invisible to the tooling. The bullet states that mechanism, not just the symptom.
  • The command is right: POST .../issues/<N>/dependencies/blocked_by with -F issue_id=<numeric id>. -F (not -f) matters — the field is an integer, and the note about id ≠ number is the trap that costs a 422 on the first attempt.
  • The cited instance checks out: obs-studio#1865 carried repeated triage verdicts between 2026-10-23 and 2026-10-27, and after linking both blockers issueDependenciesSummary.blockedBy is 2 and the issue no longer appears in a fresh workflow.coordinator list. Consistent with the coordinator skill's own warning that tasks with no label state re-list every tick.
  • Docs only: no code, labels or CI surface touched; test passes.

One optional (non-blocking) nit for a later pass: the sentence reads "with one open blocker the issue leaves triage", which could be read as "exactly one". The code path leaves triage for any non-zero blockedBy count, and the issue returns when the last blocker closes. Your wording already says the second half correctly; naming the first half as "any open blocker" would remove the ambiguity.

@zackees
zackees merged commit 28617d6 into master Oct 27, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant