bird-chinese-community/BIRD.skills / bird-troubleshooting
bird-troubleshooting
VerifiedDiagnose 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.7 KB |
| agents/openai.yaml | config | 313 B |
| evals/evals.json | config | 1.6 KB |
| metadata.json | config | 472 B |
| plugin.json | config | 554 B |
| references/troubleshooting-workflow.md | markdown | 1.8 KB |
| scripts/collect_diagnostics.py | script | 4.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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |