Implementation Plan: analyze-prs Merge Queue Detection

[Trecek]

Summary

Add GitHub merge queue awareness to the analyze-prs skill. When a merge queue is
active on the target branch, the skill uses queue-position ordering and tags all
MERGEABLE queue entries as simple. When the queue is absent or empty it falls back
to the existing file-overlap / topological-sort path. The PR manifest format is
identical in both modes.

Two files change: src/autoskillit/execution/github.py gains parse_merge_queue_response(), a pure function that extracts and normalises merge queue entries from a raw GraphQL response dict; and src/autoskillit/skills/analyze-prs/SKILL.md gains Step 0.5 (merge queue detection) and branches the existing Steps 1–4 so they are skipped or simplified when QUEUE_MODE = true.

Requirements

INFRA — Merge Queue Infrastructure

• REQ-INFRA-001: The integration branch ruleset must have merge queue enabled.
• REQ-INFRA-002: The CI workflow must include a merge_group trigger so status checks fire on gh-readonly-queue/* temporary branches.

DETECT — Merge Queue Detection

• REQ-DETECT-001: The analyze-prs skill must query the GitHub GraphQL API to determine whether a merge queue is enabled on the target branch.
• REQ-DETECT-002: The analyze-prs skill must retrieve all merge queue entries with their position, state, and associated PR metadata when a queue is detected.
• REQ-DETECT-003: The system must fall back to existing file-overlap analysis when the merge queue is not enabled or returns no entries.

ORDER — Queue-Position Ordering

• REQ-ORDER-001: When merge queue entries are available, the PR manifest must list PRs in queue-position order (ascending position field).
• REQ-ORDER-002: PRs with state: MERGEABLE in the queue must be tagged as simple in the manifest.
• REQ-ORDER-003: The manifest format must remain identical regardless of whether queue ordering or computed ordering was used.

FALLBACK — Conflict Resolution Fallback

• REQ-FALLBACK-001: If a queue-ordered PR unexpectedly conflicts during merge, the pipeline must fall back to the existing conflict resolution cycle.
• REQ-FALLBACK-002: The fallback path must not require any changes to the pr-merge-pipeline.yaml recipe structure.

Architecture Impact

Process Flow Diagram

%%{init: {'flowchart': {'nodeSpacing': 45, 'rankSpacing': 55, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef terminal    fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode   fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler     fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase       fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output      fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector    fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;

    %% TERMINALS %%
    START([START])
    DONE([COMPLETE])

    %% STEP 0 %%
    subgraph S0 ["Step 0 — Authenticate & List PRs"]
        direction TB
        ListPRs["gh pr list<br/>━━━━━━━━━━<br/>--base branch --state open<br/>--json number,title,headRefName,..."]
        ZeroPRs{"0 PRs?"}
    end

    %% STEP 0.5 %%
    subgraph S05 ["● Step 0.5 — Detect GitHub Merge Queue"]
        direction TB
        ResolveRepo["● gh repo view<br/>━━━━━━━━━━<br/>extract OWNER + REPO"]
        GraphQL["● gh api graphql<br/>━━━━━━━━━━<br/>mergeQueue(branch) entries<br/>position · state · pullRequest"]
        ParseFn["● parse_merge_queue_response()<br/>━━━━━━━━━━<br/>github.py — pure function<br/>returns sorted entry list"]
        QueueDecision{"MERGEABLE<br/>entries?"}
    end

    %% QUEUE PATH %%
    subgraph QP ["Queue Path (QUEUE_MODE = true)"]
        direction TB
        FetchMeta["gh pr view (parallel ≤8)<br/>━━━━━━━━━━<br/>headRefName · files · additions<br/>deletions · changedFiles<br/>(no diffs, no body)"]
        QueueOrder["Order by position ASC<br/>━━━━━━━━━━<br/>from QUEUE_ENTRIES<br/>overlap_with = [] for all"]
        TagSimple["Tag complexity<br/>━━━━━━━━━━<br/>MERGEABLE → simple<br/>other states → needs_check"]
    end

    %% EXISTING PATH %%
    subgraph EP ["● Existing Path (QUEUE_MODE = false)"]
        direction TB
        FetchDiffs["● Step 1: Fetch PR diffs (parallel ≤8)<br/>━━━━━━━━━━<br/>gh pr diff + gh pr view files<br/>+ requirements section"]
        CIReview["● Step 1.5: CI & Review gate<br/>━━━━━━━━━━<br/>gh pr checks · gh pr view reviews<br/>→ ELIGIBLE / CI_BLOCKED / REVIEW_BLOCKED"]
        Overlap["● Step 2: File overlap matrix<br/>━━━━━━━━━━<br/>shared_files per PR pair<br/>conflict if shared_files ≠ []"]
        TopoSort["● Step 3: Topological sort<br/>━━━━━━━━━━<br/>no-overlap first (additions ASC)<br/>then overlap graph order"]
        TagComplex["● Step 4: Tag complexity<br/>━━━━━━━━━━<br/>simple / needs_check<br/>per overlap + size rules"]
    end

    %% STEP 5 %%
    subgraph S5 ["Step 5 — Write Outputs (identical format both modes)"]
        direction TB
        WriteJSON["pr_order_{ts}.json<br/>━━━━━━━━━━<br/>integration_branch · base_branch<br/>prs · ci_blocked_prs · review_blocked_prs"]
        WriteMD["pr_analysis_plan_{ts}.md<br/>━━━━━━━━━━<br/>human-readable plan<br/>notes queue source when QUEUE_MODE"]
    end

    S6["Step 6: Verify & Report<br/>━━━━━━━━━━<br/>validate JSON · emit output tokens"]

    %% FLOW %%
    START --> ListPRs
    ListPRs --> ZeroPRs
    ZeroPRs -->|"yes — empty manifest"| DONE
    ZeroPRs -->|"no"| ResolveRepo
    ResolveRepo --> GraphQL
    GraphQL -->|"parse response"| ParseFn
    ParseFn --> QueueDecision

    QueueDecision -->|"yes → QUEUE_MODE=true"| FetchMeta
    QueueDecision -->|"no → QUEUE_MODE=false"| FetchDiffs
    GraphQL -->|"error (auth/rate/network)"| FetchDiffs

    FetchMeta --> QueueOrder --> TagSimple
    FetchDiffs --> CIReview --> Overlap --> TopoSort --> TagComplex

    TagSimple  --> WriteJSON
    TagComplex --> WriteJSON
    WriteJSON  --> WriteMD
    WriteMD    --> S6
    S6         --> DONE

    %% CLASS ASSIGNMENTS %%
    class START,DONE terminal;
    class ZeroPRs,QueueDecision stateNode;
    class ListPRs,FetchDiffs,CIReview,Overlap,TopoSort,TagComplex handler;
    class ResolveRepo,GraphQL,ParseFn newComponent;
    class FetchMeta,QueueOrder,TagSimple newComponent;
    class WriteJSON,WriteMD output;
    class S6 phase;

Loading

Color Legend:

Color	Category	Description
Dark Blue	Terminal	START / COMPLETE states
Teal	State	Decision points (0-PR exit, QUEUE_MODE branch)
Orange	Handler	Existing processing steps
Green (●)	Modified	Merge queue detection steps — github.py + SKILL.md
Dark Teal	Output	Written manifest files
Purple	Phase	Verify & Report

Closes #347

Implementation Plan

Plan file: /home/talon/projects/autoskillit-runs/merge-queue-20260311-214047-666786/temp/make-plan/analyze_prs_merge_queue_plan_2026-03-11_120000.md

Token Usage Summary

Token Summary

fix

• input_tokens: 629
• output_tokens: 243257
• cache_creation_input_tokens: 826397
• cache_read_input_tokens: 45631198
• invocation_count: 12
• elapsed_seconds: 5893.771816905999

resolve_review

• input_tokens: 391
• output_tokens: 168303
• cache_creation_input_tokens: 449347
• cache_read_input_tokens: 21658363
• invocation_count: 7
• elapsed_seconds: 4158.092358417003

audit_impl

• input_tokens: 2756
• output_tokens: 166320
• cache_creation_input_tokens: 581154
• cache_read_input_tokens: 4335466
• invocation_count: 13
• elapsed_seconds: 4878.894512576997

open_pr

• input_tokens: 239
• output_tokens: 155616
• cache_creation_input_tokens: 470597
• cache_read_input_tokens: 7709497
• invocation_count: 9
• elapsed_seconds: 3999.4891979619897

review_pr

• input_tokens: 177
• output_tokens: 244448
• cache_creation_input_tokens: 479046
• cache_read_input_tokens: 6204544
• invocation_count: 7
• elapsed_seconds: 4626.790592216992

plan

• input_tokens: 1665
• output_tokens: 187361
• cache_creation_input_tokens: 655841
• cache_read_input_tokens: 11017819
• invocation_count: 8
• elapsed_seconds: 3779.893521053007

verify

• input_tokens: 8274
• output_tokens: 151282
• cache_creation_input_tokens: 664012
• cache_read_input_tokens: 12450916
• invocation_count: 10
• elapsed_seconds: 3138.836677256011

implement

• input_tokens: 785
• output_tokens: 269097
• cache_creation_input_tokens: 876108
• cache_read_input_tokens: 61001114
• invocation_count: 10
• elapsed_seconds: 6131.576118467008

analyze_prs

• input_tokens: 15
• output_tokens: 29915
• cache_creation_input_tokens: 67472
• cache_read_input_tokens: 374939
• invocation_count: 1
• elapsed_seconds: 524.8599999569997

merge_pr

• input_tokens: 166
• output_tokens: 56815
• cache_creation_input_tokens: 314110
• cache_read_input_tokens: 4466380
• invocation_count: 9
• elapsed_seconds: 1805.746022643012

create_review_pr

• input_tokens: 27
• output_tokens: 20902
• cache_creation_input_tokens: 62646
• cache_read_input_tokens: 856008
• invocation_count: 1
• elapsed_seconds: 444.64073076299974

resolve_merge_conflicts

• input_tokens: 88
• output_tokens: 52987
• cache_creation_input_tokens: 122668
• cache_read_input_tokens: 7419558
• invocation_count: 1
• elapsed_seconds: 975.0682389580033

Timing Summary

fix

• total_seconds: 5893.887897783006
• invocation_count: 12

resolve_review

• total_seconds: 4158.092358417003
• invocation_count: 7

audit_impl

• total_seconds: 4878.975284532004
• invocation_count: 13

open_pr

• total_seconds: 3999.5348451210048
• invocation_count: 9

review_pr

• total_seconds: 4626.790592216992
• invocation_count: 7

plan

• total_seconds: 3780.017026652018
• invocation_count: 8

verify

• total_seconds: 3138.9388441649935
• invocation_count: 10

implement

• total_seconds: 6131.693511301022
• invocation_count: 10

analyze_prs

• total_seconds: 524.8599999569997
• invocation_count: 1

merge_pr

• total_seconds: 1805.746022643012
• invocation_count: 9

create_review_pr

• total_seconds: 444.64073076299974
• invocation_count: 1

resolve_merge_conflicts

• total_seconds: 975.0682389580033
• invocation_count: 1

clone

• total_seconds: 14.340457123005763
• invocation_count: 3

update_ticket

• total_seconds: 1.0304174909979338
• invocation_count: 1

capture_base_sha

• total_seconds: 0.00960076300543733
• invocation_count: 3

create_branch

• total_seconds: 1.9964898860052926
• invocation_count: 3

push_merge_target

• total_seconds: 2.7216036769968923
• invocation_count: 3

test

• total_seconds: 394.38787825701
• invocation_count: 6

merge

• total_seconds: 395.920931871995
• invocation_count: 3

push

• total_seconds: 1.8540772910200758
• invocation_count: 2

🤖 Generated with Claude Code via AutoSkillit

[Trecek]

[warning] arch: The except clause catches only AttributeError and TypeError, but an error in any single node iteration silently drops ALL subsequent entries rather than skipping just the bad node. Per-iteration error handling would preserve valid entries.

[Trecek]

[warning] bugs: node.get("position", 0) defaults to 0 for missing position keys. Multiple entries with missing positions all receive position=0, making their relative sort order undefined (unstable). Use a distinct sentinel (e.g. float('inf')) to make missing-position entries sort to the end.

[Trecek]

[warning] arch: In QUEUE_MODE, Step 1 fetches gh pr view {number} --json headRefName,files,... but the files field returns an array of objects (each with path, additions, deletions), not a list of plain paths. The instruction omits the .files[].path extraction step, so files_changed will be a list of dicts rather than strings, breaking downstream overlap and tagging steps.

[Trecek]

[warning] cohesion: QUEUE_MODE and QUEUE_ENTRIES are introduced in Step 0.5 but have no single authoritative definition or variable declaration section. Their semantics are repeated inline across Steps 1, 1.5, 2, 3, and 4, scattering the feature definition rather than defining once and referencing.

[Trecek]

[warning] cohesion: The Integration Strategy template uses curly-brace literal syntax {If QUEUE_MODE = true, add: ...} while all other conditional branches throughout the skill use markdown bold - **If QUEUE_MODE = true**: notation. The mixed notation styles are inconsistent.

[Trecek]

AutoSkillit review found 5 blocking issues. See inline comments.

[Trecek]

AutoSkillit PR Review — Verdict: changes_requested

Note: GitHub prevents requesting changes on your own PR. Posting as COMMENT instead.

6 blocking findings across defense, cohesion, bugs, and tests dimensions. See inline comments.

[Trecek]

[warning] defense: parse_merge_queue_response uses bare dict for both the data parameter and return type. Use dict[str, object] or a TypedDict to enforce shape at the boundary and provide type safety for nested access patterns.

[Trecek]

[warning] bugs: Mutable {} literal used as the default in queue.get("entries", {}). While harmless here (never mutated), idiomatic Python uses None with or {} for clarity and to avoid accidental mutation in future refactors.

[Trecek]

[warning] defense: GraphQL errors in the response (e.g. a {"errors": [...]} response) are silently swallowed — the function returns [] with no indication an error occurred vs. a legitimately empty queue. Callers cannot distinguish a permission error from an empty queue, masking access failures.

[Trecek]

[warning] cohesion: In the QUEUE_MODE = true branch of Step 1.5, CI_BLOCKED_PRS and REVIEW_BLOCKED_PRS are described as empty but not explicitly initialized (no bash array assignment shown), while the QUEUE_MODE = false branch initializes them with explicit CI_BLOCKED_PRS=() declarations. Step 5 manifest writing may reference unset variables in queue mode.

[Trecek]

[warning] cohesion: The QUEUE_MODE = true conditional for Integration Strategy is placed before the template prose placeholder ({2-3 sentences...}), breaking the consistent inline-branch pattern used throughout Steps 1-4. Move it inside the template section or document why this placement differs.

[Trecek]

[warning] bugs: test_parse_merge_queue_response_malformed_node_skipped asserts that a node with a missing pullRequest key is included with pr_number=None. However, the parse_merge_queue_response docstring states the function returns an empty list for unexpected structure. Either update the docstring to document that missing keys yield null fields, or fix the implementation to skip such nodes (and assert len(entries) == 0).

[Trecek]

[warning] tests: Test name test_parse_merge_queue_response_malformed_node_skipped says the entry is skipped, but the assertion shows it IS included with pr_number=None. The comment contradicts the test name. Rename to test_parse_merge_queue_response_missing_pullrequest_included_with_none to accurately describe the behavior.