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

references/troubleshooting-workflow.md

View on GitHub
# Troubleshooting Layers

## Baseline

```bash
uv run scripts/collect_diagnostics.py --root .
```

The collector reports platform, `birdcc`, `bird`, and `birdc` versions, project config names, and
bounded candidate config discovery. It does not contact the daemon or modify files.

## Layer map

| Layer | Evidence | Typical cause |
| --- | --- | --- |
| Project discovery | `birdcc init --dry-run --json` | wrong entry, fragment selected, ambiguous workspace |
| Static analysis | `birdcc lint --json` | parser, symbol, rule, or include-graph issue |
| Native parse | matching `bird -p -c` | version mismatch, include environment, permissions, generated inputs |
| Control socket | read-only `birdc show status/protocols/route` | daemon state, session, filter, or socket mismatch |
| Logs/core | narrow timestamped excerpt/stack | runtime or environment failure |
| Source | exact revision and call path | upstream bug or version-specific semantics |

Passing one layer does not prove the next.

## Symptom routes

- Cannot open config: verify the configured entry, working directory, containment, permissions,
  and service-unit arguments.
- Lint passes, parse fails: compare the `bird` major/minor version and the complete include
  environment.
- Parse passes, reload fails: preserve the reload error and compare live-state constraints; do not
  restart as the first diagnostic step.
- Routes missing: inspect protocol/channel state, import/export filters, table selection, and
  relevant routes with read-only `birdc`.
- Crash/assertion: identify binary build and symbols, capture a narrow backtrace, then use
  `bird-source-explorer`.

## Reporting

For each hypothesis provide:

1. supporting evidence;
2. contradicting or missing evidence;
3. one read-only falsifying check;
4. risk and rollback needs for a future fix.
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