Skip to content

bird-chinese-community/BIRD.skills / bird-troubleshooting

bird-troubleshooting

Verified

Diagnose active BIRD daemon incidents across config, runtime, environment, sockets, logs, source, and tooling. Use when BIRD fails to start or reload, crashes, loses sessions/routes, behaves differently after lint passes, or when birdcc and bird -p disagree. Collect read-only evidence first, protect routing secrets, and route isolated config edits to bird-agent or pure implementation research to bird-source-explorer.

FileKindSize
SKILL.mdskill md2.7 KB
agents/openai.yamlconfig313 B
evals/evals.jsonconfig1.6 KB
metadata.jsonconfig472 B
plugin.jsonconfig554 B
references/troubleshooting-workflow.mdmarkdown1.8 KB
scripts/collect_diagnostics.pyscript4.4 KB

scripts/collect_diagnostics.py

View on GitHub
# /// script
# requires-python = ">=3.10"
# dependencies = []
# ///

"""Collect baseline BIRD tooling diagnostics."""

from __future__ import annotations

import argparse
import json
import os
import platform
import shutil
import subprocess
from pathlib import Path

CONFIG_NAMES = {"bird.config.json", "birdcc.config.json"}
CONFIG_SUFFIXES = (".conf", ".bird", ".bird2", ".bird3")
MAX_OUTPUT_CHARS = 8192


def run(cmd: list[str]) -> str | None:
    exe = shutil.which(cmd[0])
    if not exe:
        return None
    try:
        result = subprocess.run(
            [exe, *cmd[1:]],
            capture_output=True,
            text=True,
            timeout=10,
            check=False,
        )
        output = (result.stdout.strip() or result.stderr.strip()) or None
        if output is not None and len(output) > MAX_OUTPUT_CHARS:
            return output[:MAX_OUTPUT_CHARS] + "\n[truncated]"
        return output
    except Exception as exc:
        return f"error: {exc}"


def birdcc_package_version() -> str | None:
    executable = shutil.which("birdcc")
    if not executable:
        return None
    try:
        resolved = Path(executable).resolve(strict=True)
    except OSError:
        return None

    for parent in (resolved.parent, *list(resolved.parents)[:6]):
        package_json = parent / "package.json"
        if not package_json.is_file():
            continue
        try:
            package = json.loads(package_json.read_text(encoding="utf-8"))
        except (OSError, json.JSONDecodeError):
            continue
        if package.get("name") == "@birdcc/cli" and isinstance(
            package.get("version"), str
        ):
            return package["version"]
    return None


def _is_within_root(path: Path, root: Path) -> bool:
    """Return True if path is the same as or inside root after resolving symlinks."""
    try:
        path.resolve().relative_to(root.resolve())
    except (ValueError, OSError):
        return False
    return True


def detect_files(root: Path, max_depth: int) -> tuple[list[str], list[str]]:
    configs: list[str] = []
    project_configs: list[str] = []

    for current, dirnames, filenames in os.walk(root, followlinks=False):
        current_path = Path(current)
        depth = len(current_path.relative_to(root).parts)
        dirnames[:] = [
            name
            for name in dirnames
            if not (current_path / name).is_symlink()
            and name not in {".git", "node_modules", ".pnpm-store"}
            and depth < max_depth
        ]

        for filename in filenames:
            path = current_path / filename
            if path.is_symlink() or not path.is_file() or not _is_within_root(path, root):
                continue
            relative = str(path.relative_to(root))
            if filename in CONFIG_NAMES:
                project_configs.append(relative)
            elif filename.endswith(CONFIG_SUFFIXES):
                configs.append(relative)

    return sorted(configs), sorted(project_configs)


def main() -> None:
    parser = argparse.ArgumentParser(description="Collect BIRD diagnostics")
    parser.add_argument("--root", default=".", help="Workspace root to scan")
    parser.add_argument(
        "--max-depth",
        type=int,
        default=4,
        help="Maximum directory depth for file discovery (default: 4)",
    )
    args = parser.parse_args()

    root = Path(args.root).resolve()
    if not root.is_dir():
        parser.error(f"--root must be a directory: {root}")
    if args.max_depth < 0:
        parser.error("--max-depth must be non-negative")

    config_files, project_configs = detect_files(root, args.max_depth)
    birdcc_version = birdcc_package_version()
    data = {
        "platform": {
            "system": platform.system(),
            "release": platform.release(),
            "machine": platform.machine(),
        },
        "birdcc_bin": shutil.which("birdcc"),
        "birdcc_available": run(["birdcc", "--help"]) is not None,
        "birdcc_version": birdcc_version,
        "birdcc_version_source": "package.json" if birdcc_version else None,
        "bird_bin": shutil.which("bird"),
        "bird_version": run(["bird", "--version"]),
        "birdc_bin": shutil.which("birdc"),
        "birdc_version": run(["birdc", "--version"]),
        "project_configs": project_configs,
        "config_files": config_files,
    }

    print(json.dumps(data, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall