diagnose-awf

Diagnose AWF Failures

Single entry point for diagnosing AWF failures. The canonical knowledge lives in the diagnosis registry — this skill only routes and reports.

Procedure

1. Read the index — docs/diagnostics/README.md for boundary routing and specialist references, and docs/diagnostics/agent-playbook.md for the report shape and safety rules.

2. Fingerprint the run: AWF version, runner type (GitHub-hosted / self-hosted / ARC+DinD / GHES / GHEC), DOCKER_HOST, GITHUB_SERVER_URL, container runtime, provider, auth mode. Use unknown where unverified.

3. Classify the failing boundary: runner, runtime, network, auth, ci, security.

4. Load only matching records:

   npx tsx scripts/diagnostics/cli.ts search "<redacted error string>" --boundary <boundary>
   

   Without a clone, use the portable artifact .github/agents/diagnose-awf.md (prefer a tag matching your AWF version).

5. Probe with the matched finding's read-only probe when the match is ambiguous — one probe at a time.

6. Report: observed symptom, matched finding ID and evidence, affected version/topology, safe next probe, fix/workaround, citations.

Auth routing

• api-proxy sidecar / provider token exchange → AUTH-001, AUTH-002
• GitHub/Copilot enterprise and BYOK routing → AUTH-001, docs/auth-matrix.md
• gh-aw-launched mcpg HTTP MCP GitHub OIDC → AUTH-003

Check configuration presence/shape, route and health status, and redacted error classes only.

Safety rules

• Never request API keys, tokens, JWTs, Authorization headers, environment dumps, inference probes, or token exchanges.
• Never recommend --env-all, disabling isolation, or broadening the domain allowlist by default.
• Suspected isolation or credential-boundary regressions route to SEC-001 and the repository security review process.
• If no record matches, say so, name the smallest missing evidence, and stop. Never invent a fix.

Specialist references

• .github/workflows/shared/self-hosted-failure-modes.md — full runner catalog
• .github/skills/debug-firewall/SKILL.md — Squid, iptables, container state
• .github/skills/awf-debug-tools/SKILL.md — log parsing helpers
• .github/skills/debugging-workflows/SKILL.md — GitHub Actions log retrieval
• docs/auth-matrix.md, docs/compatibility.md, docs/troubleshooting.md

Updating knowledge

Follow docs/diagnostics/patterns.md. Edit the canonical record, run npm run diagnostics:render, and open a reviewed PR. Never edit generated artifacts or .lock.yml files by hand.