network-collection-triage

name: network-collection-triage description: >- Triage bug reports, CI failures, and GitHub issues across Ansible network collections (cisco.ios, cisco.iosxr, cisco.nxos, arista.eos, ansible.netcommon, ansible.utils, etc.). Two modes: scan mode for bulk weekly triage across all repos, and direct mode for deep triage of a single issue. Network-specific: uses cross-collection cascade detection for shared dependencies (netcommon, utils) and known network CI failure patterns. Outputs structured JSON and markdown. Use when asked to triage network issues, scan network issues, weekly triage, triage CI failure, or triage collection issue. Do not use for non-network collections or general Ansible questions. triggers: - triage network issues - triage network - scan network issues - weekly triage - triage CI failure - triage collection issue user-invocable: true allowed-tools: - Bash - Read - Write - Glob - Grep argument-hint: "[] [--scan]"

Skill: network-collection-triage

Purpose

Triage bug reports, CI failures, and GitHub issues across Ansible network collections. Categorize items, check known network CI failure patterns, assess severity with cross-collection cascade detection for shared dependencies (ansible.netcommon, ansible.utils, ansible.pylibssh), and produce structured JSON and markdown output suitable for downstream dashboards or reports.

Why network-specific

This skill exists in network_content rather than ansible-collection-sdlc because the triage logic depends on network-specific domain knowledge:

• Cross-collection cascade detection tied to the ansible.netcommon and ansible.utils and ansible.pylibssh dependency chain shared by all network collections
• Known CI failure patterns specific to network collection CI (Galaxy version lag for netcommon, persistent connection timeout leaks, etc.)
• Scoped repo list — queries a fixed set of network collection repositories under the ansible-collections GitHub org

A generic collection triage skill would not have this domain knowledge.

When to Invoke

TRIGGER when:

• A user asks to triage network collection issues or CI failures
• A user asks to scan repos for unassigned bugs/PRs (scan mode)
• A user pastes a GitHub issue URL or CI failure link for a network collection
• A user asks for a weekly triage report
• A user says "triage network", "scan network issues", or "weekly triage"

DO NOT TRIGGER when:

• The issue is in a non-network collection (use generic triage instead)
• The user is asking general Ansible questions unrelated to triage
• The user wants to fix a bug (use a bugfix workflow instead)

Prerequisites

• gh CLI installed and authenticated (gh auth status)
• Push access not required — this skill only reads GitHub data

Mode Detection

This skill has TWO modes. Detect the mode from the user's trigger and act accordingly. Do NOT ask clarifying questions in scan mode.

Scan mode (no specific issue provided)

Any trigger that does NOT include a specific GitHub URL or issue number runs scan mode. This includes: "triage network issues", "triage network", "scan network issues", "weekly triage", "generate triage report".

When scan mode is triggered: immediately run the full pipeline end-to-end without asking the user for any input. Do NOT stop to ask "What would you like me to triage?" — the whole point of scan mode is zero-input bulk triage.

Direct mode (specific issue provided)

A user pastes a GitHub issue URL, CI failure link, error log, or describes a specific bug symptom. In this mode (and ONLY this mode), ask the user for additional context if needed (collection, platform, Ansible version).

Collections in Scope

GitHub org: ansible-collections

Scan Mode Pipeline

Execute all steps automatically without stopping for user input.

Step 1 — Fetch open issues and PRs across all repos

Use gh to query each repo in scope. Fetch open issues and open pull requests from the last 14 days (configurable).

For bugs (issues):

gh issue list --repo ansible-collections/cisco.ios --state open \
  --search "updated:>=YYYY-MM-DD" --json number,title,url,labels,createdAt,author,assignees --limit 50 --search "-label:stale"

For pull requests:

gh pr list --repo ansible-collections/cisco.ios --state open \
  --search "updated:>=YYYY-MM-DD draft:false" \
  --json number,title,url,labels,createdAt,author,isDraft,reviewDecision \
  --limit 50 --search "-label:stale"

Run these for every repo in the Collections in Scope table:

ansible-collections/ansible.netcommon
ansible/pylibssh
ansible-collections/ansible.utils
ansible-collections/cisco.ios
ansible-collections/cisco.iosxr
ansible-collections/cisco.nxos
ansible-collections/arista.eos
ansible-collections/cisco.asa
ansible-collections/vyos.vyos
ansible-collections/ansible.scm

Filter and record results based on the timeline (default: T-14 days)

• Ignore PRs where isDraft is True
• Ignore closed issues
• Ignore closed/merged PRs
• Ignore any issue or PR that is labelled as 'stale'
• Group by repository and type (issue vs PR)
• Store ALL items for the complete listing section (no filtering at this stage)

Combine all results into a single list for processing.

Step 2 — Check CI status for each repo

For each repo, check the latest CI workflow run status:

gh run list --repo ansible-collections/cisco.ios --workflow tests.yml \
  --json status,conclusion,headBranch,createdAt,url --limit 5 --branch main

Note any repos where the main branch CI is currently failing — this feeds into cross-collection signal detection step.

Use the five most recent runs from the query (--limit 5). Count a run as passing only when conclusion is success; any other conclusion or a missing run slot counts as non-passing for health (green 5/5, yellow 3–4/5, red 0–2/5).

Step 3 — Categorize every item

Examine each issue/PR title, labels, and body to assign a category:

Heuristics for categorization:

• Label bug or title contains "fix", "broken", "error" → Bug report
• Title references another collection's PR/issue or "bump dependency" → Downstream fix
• Label enhancement or feature or title contains "add support" → New feature PR
• Title mentions "test", "molecule", "mock", "integration target" → Test infrastructure
• Title mentions "dependabot", "bump", "ci:", "chore:", "linting" → Chore

Key distinction: A Molecule/CISSHGO PR building mock-device test scenarios is test INFRASTRUCTURE (Minor). A Dependabot bump or pyproject.toml cleanup is a Chore (Trivial).

Step 4 — Check for known CI failure patterns

Check whether any failing CI or reported issue matches a known pattern. If a known pattern matches, note it in the triage output and use the documented resolution rather than investigating from scratch.

Pattern 1 — Galaxy version lag: Unit CI (unit-galaxy job) fails with an error already fixed in ansible.netcommon or ansible.utils main but not yet released to Galaxy. The unit-galaxy job installs the last Galaxy release, so fixes in main don't reach it until a new release is cut. Resolution: Cut a netcommon/utils release, or temporarily pin to git source.

Pattern 2 — devel/milestone only failure: CI fails only on devel or milestone ansible-core versions due to an API change or deprecation not yet adapted. Check ansible-core changelog. Resolution: May be needs_revision; adapt to new API.

Pattern 3 — Cross-PR dependency: PR passes CI independently but fails when merged due to an unmerged dependency (e.g. a netcommon fix that this PR depends on). Resolution: Merge dependencies in correct order.

Pattern 4 — Persistent connection state leak: A test task sets connection options (e.g. ansible_command_timeout) via include_tasks vars:. The persistent connection daemon caches the value and does not reset it when the task scope ends, causing subsequent tasks to fail with stale values. Resolution: Add ansible.builtin.meta: reset_connection after the test.

Step 5 — Apply severity escalators

Escalators can only raise severity, never lower it.

Step 6 — Detect cross-collection signals

If a bug or failing CI is in ansible.netcommon, ansible.utils or ansible.pylibssh:

• List all downstream collections importing the affected code
• Check if their CI is currently failing (from Step 2 data)
• If multiple collections failing → cascade event
• Priority action: fix in netcommon/utils → cut release → re-trigger downstream CI

Dependency chain:

ansible.pylibssh ──→ ansible.netcommon
ansible.netcommon ──→ cisco.ios, cisco.iosxr, cisco.nxos,
                      arista.eos, cisco.asa, vyos.vyos
ansible.utils ────→ (same downstream consumers), ansible.scm

Step 7 — Generate structured output

Save two files:

1. triage-report-YYYY-MM-DD.json — structured triage data (see JSON Output Schema)
2. triage-report-YYYY-MM-DD.md — human-readable markdown summary

The JSON file is the primary output — it can be loaded by a separate dashboard frontend or consumed by other tools. The markdown file is for quick human review.

Validate the JSON before finishing:

python network-collection-triage/scripts/validate_triage_report.py triage-report-YYYY-MM-DD.json

Fix any schema or consistency errors reported by the validator.

Step 7.1 — Present results

Share both file links and a brief summary: total items, breakdown by severity, any critical items or cross-collection signals that need immediate attention.

Step 7.2 — Generate the markdown

Create a detailed markdown report of the triage results, ensuring all the issues and PRs are listed in the report. It should be written in the user's current working directory.

Step 7.3 — Generate the JSON

Generate a JSON file of the triage results, ensuring all the issues and PRs are listed in the JSON file. It should be written in the user's current working directory. Do not use any summary data from the markdown, utilize the data generated from relevant commands and generate the json. The format of the JSON file should be as mentioned below:

Output — JSON schema

The canonical JSON Schema lives at schema/triage-report.schema.json (relative to this skill directory). The agent must emit valid JSON (UTF-8) that passes scripts/validate_triage_report.py. Top-level shape:

repositories[] entry

ci-status object (per repo; set to null when gh run list failed for that repo)

ci-status.runs[] entry

Issue row (repositories[].issues[])

Pull request row (repositories[].pullRequests[])

Same fields as Issue row, plus:

priorityMatrix buckets (critical/high/medium/low) are separate from per-item triage severity (critical/major/minor/trivial above).

Completeness: sum(repositories[].issues.length) must equal the open issues you analyzed for the listing (per workflow rules); same for PRs. Nothing omitted for brevity.

Direct Mode Steps

Step 1 — Identify collection and component

Determine which collection, which module/plugin, and what connection type. If a GitHub URL is provided, fetch the issue or PR details:

gh issue view <number> --repo ansible-collections/<collection> --json title,body,labels,comments

or:

gh pr view <number> --repo ansible-collections/<collection> --json title,body,labels,files,statusCheckRollup

Step 2 — Check for known CI failure patterns

Check whether the failure matches a known pattern (see Step 4 in scan mode). If a known pattern matches, document it and skip to resolution.

Step 3 — Cross-collection dependency check

If the bug is in ansible.netcommon, ansible.utils or ansible.pylibssh, check the dependency chain (same as scan mode Step 6).

Step 4 — Apply severity escalators

Same table as scan mode Step 5.

Step 5 — Produce triage report

Use the Output Format below.

Output Format

Every triage produces this structured report:

## Network Collection Triage Report

**Date**: [date]
**Mode**: [Scan / Direct]

### Issue
[GitHub issue URL or CI failure link]

### Collection: [e.g. cisco.ios]
### Component: [module name, plugin, or CI infrastructure]
### Ansible Version: [e.g. stable-2.19 / devel]
### Connection Type: [network_cli / netconf / httpapi]

### Category
[Downstream fix / New feature / Bug report / Chore-CI / Test improvement]

### Severity: [Critical / Major / Minor / Trivial]
[Justification, including any escalators applied]

### Known Pattern Match
[Matched pattern name, OR "No known pattern — new issue"]

### Cross-Collection Impact
[None / List of affected collections / Cascade event detected]

### Root Cause
[Technical explanation if identified]

### Recommended Resolution
[Specific action: cut release, fix in PR #N, add meta: reset_connection, etc.]

Error Handling

• gh not authenticated: Run gh auth status. If not logged in, inform user to run gh auth login and stop.
• Rate limiting: GitHub API has rate limits. If hitting limits during scan mode, space out requests or reduce the repo list to critical collections first (netcommon, utils, pylibssh, ios, iosxr, nxos, eos, scm).
• Empty results: If no open bugs or PRs are found for a repo, skip it silently. If ALL repos return empty, report "No open items found across network collections" and confirm the time window.
• Repo not found: If gh returns a 404 for a repo, skip it and note the skip in the output. The repo may have been renamed or archived.