PopeBot Doctor - Environment Diagnostics & Repair

A comprehensive diagnostic system inspired by ZeroClaw's doctor architecture. This skill enables agents to perform thorough health checks of the PopeBot environment, identify issues, and perform automated repairs.

Purpose

When enabled, PopeBot Doctor allows the agent to:

Diagnose - Run comprehensive health checks across all system components
Verify - Check skill integrity, API connectivity, and configuration
Report - Generate detailed diagnostic reports with severity ratings
Repair - Perform automated fixes for common issues
Monitor - Track system health over time

Categories Checked

🔧 Environment

Docker availability and version
Node.js runtime version
Git configuration
GitHub CLI authentication
Required command-line tools

📦 Skills Health

Skill directory structure validation
SKILL.md frontmatter parsing
Missing dependency detection
Broken symlink detection

🌐 API Connectivity

Network connectivity tests
API endpoint health (GitHub, LLM providers, etc.)
Authentication token validation
Rate limit status

⚙️ Configuration

Required environment variables
Config file syntax validation
Secret availability checks
Permission validations

📁 File System

Workspace structure integrity
Log directory health
Required file presence
Permission checks

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      PopeBot Doctor Pipeline                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐  │
│  │ COLLECT│───▶│ ANALYZE  │───▶│  REPORT  │───▶│  REPAIR  │  │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘  │
│                                                                  │
│  • Gather data  • Run checks   • Generate    • Auto-fix        │
│  • Run tests    • Score issues   diagnostics   • Suggest        │
│  • Check APIs   • Categorize   • Export JSON   fixes          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Setup

cd /job/.pi/skills/popebot-doctor
npm install

Tools Added

When this skill is active, the following tools are available:

`popebot_doctor_run`

Run comprehensive diagnostics and return results.

// Full diagnostic run
await popebot_doctor_run({})

// Check specific categories only
await popebot_doctor_run({ categories: ["environment", "skills"] })

// Include automated repairs
await popebot_doctor_run({ autoRepair: true })

// Output as JSON for programmatic use
await popebot_doctor_run({ format: "json" })

`popebot_doctor_check`

Quick health check - returns pass/fail.

// Quick check
const healthy = await popebot_doctor_check({})

// Check specific area
const skillsHealthy = await popebot_doctor_check({ category: "skills" })

`popebot_doctor_repair`

Attempt to fix detected issues.

// Repair all fixable issues
await popebot_doctor_repair({ all: true })

// Repair specific category
await popebot_doctor_repair({ category: "skills" })

// Dry run - show what would be fixed
await popebot_doctor_repair({ dryRun: true })

`popebot_doctor_report`

Generate formatted diagnostic reports.

// Generate report
await popebot_doctor_report({ format: "markdown" })

// Save to file
await popebot_doctor_report({ output: "/tmp/doctor-report.md" })

// Include only errors
await popebot_doctor_report({ severity: "error" })

CLI Commands

`popebot-doctor`

Run diagnostics from command line.

# Full diagnostic
popebot-doctor

# Quick check
popebot-doctor --quick

# Check specific categories
popebot-doctor --categories environment,skills

# Auto-repair
popebot-doctor --repair

# JSON output
popebot-doctor --json

# Save report
popebot-doctor --output report.md

`popebot-doctor-check`

Quick health check with exit codes.

# Exit 0 if healthy, 1 if issues found
popebot-doctor-check

# Check specific category
popebot-doctor-check --category api

Severity Levels

Level	Icon	Description	Action Required
OK	✅	All checks passed	None
Warning	⚠️	Non-critical issue	Review recommended
Error	❌	Critical issue	Fix required

Diagnostic Categories

Environment Checks

Check	Description	Severity if Failed
Node.js version	Node.js 18+ required	Error
Docker	Docker available	Warning
Git	Git configured	Error
GitHub CLI	gh authenticated	Warning

Skills Checks

Check	Description	Severity if Failed
SKILL.md exists	Required metadata file	Error
Valid frontmatter	YAML frontmatter parseable	Error
Scripts executable	Scripts have execute permission	Warning
Dependencies installed	node_modules present	Warning
Symlink integrity	No broken symlinks	Error

API Checks

Check	Description	Severity if Failed
GitHub API	Can reach api.github.com	Error
LLM provider	LLM API responsive	Error
Network	External connectivity	Error

Configuration Checks

Check	Description	Severity if Failed
Required vars	Critical env vars set	Error
Optional vars	Optional env vars present	Warning
Config syntax	JSON/TOML valid	Error

Usage in Agent Prompt

When this skill is active, include this context:

## PopeBot Doctor - Environment Diagnostics

You have access to a comprehensive diagnostic system (PopeBot Doctor) inspired by ZeroClaw's doctor architecture.

### Purpose

Use PopeBot Doctor to:
- Run comprehensive health checks of the environment
- Diagnose skill configuration issues
- Test API connectivity and authentication
- Validate file system integrity
- Perform automated repairs

### Diagnostic Categories

1. **Environment**: Node.js, Docker, Git, GitHub CLI
2. **Skills**: Skill structure, dependencies, symlinks
3. **API**: Network connectivity, API endpoints
4. **Config**: Environment variables, file syntax
5. **Filesystem**: Workspace structure, permissions

### Severity Levels

- ✅ OK - All checks passed
- ⚠️ Warning - Non-critical issue, review recommended
- ❌ Error - Critical issue, fix required

### Key Commands

**popebot_doctor_run()** - Run full diagnostics
- Example: await popebot_doctor_run({ autoRepair: true })

**popebot_doctor_check()** - Quick health check
- Example: await popebot_doctor_check({ category: "skills" })

**popebot_doctor_repair()** - Attempt automated fixes
- Example: await popebot_doctor_repair({ dryRun: true })

**popebot_doctor_report()** - Generate formatted reports
- Example: await popebot_doctor_report({ format: "markdown" })

### Workflow

1. DIAGNOSE: Run popebot_doctor_run() to collect diagnostics
2. ANALYZE: Review severity levels and identify issues
3. REPAIR: Use popebot_doctor_repair() for auto-fixable issues
4. REPORT: Generate a report for documentation

### Example

```javascript
// Run full diagnostics
const results = await popebot_doctor_run({});

// Check if any errors
const hasErrors = results.items.some(i => i.severity === "error");

if (hasErrors) {
  // Try auto-repair
  const repairResult = await popebot_doctor_repair({ all: true });
  
  // Generate report
  await popebot_doctor_report({ output: "/tmp/fix-report.md" });
}

Best Practices

Run diagnostics before major changes - Establish baseline health
Review warnings too - They may become errors later
Use dry-run first - Test repairs before applying
Check after repairs - Verify fixes resolved issues
Save reports - Document system health over time


## File Structure

.pi/skills/popebot-doctor/ ├── SKILL.md # This documentation ├── package.json # Dependencies ├── index.js # Main entry / exports ├── lib/ │ ├── diagnostics.js # Core diagnostic runners │ ├── environment.js # Environment checks │ ├── skills.js # Skill health checks │ ├── api.js # API connectivity tests │ ├── config.js # Configuration validation │ ├── filesystem.js # File system checks │ ├── repair.js # Auto-repair logic │ └── report.js # Report generation ├── bin/ │ ├── popebot-doctor.js # CLI entry │ └── popebot-doctor-check.js # Quick check CLI ├── templates/ │ └── DOCTOR_REPORT.md # Report template └── test/ └── doctor.test.js # Unit tests


## Integration with Other Skills

### With skill-scout

Use before installing new skills:
```javascript
// Run diagnostics first
const health = await popebot_doctor_run({ categories: ["skills"] });

if (health.summary.errors === 0) {
  // Safe to install new skills
  await skill_scout_install({ name: "new-skill" });
} else {
  // Fix issues first
  await popebot_doctor_repair({ category: "skills" });
}

With heartbeat

Integrate with periodic health checks:

// In HEARTBEAT.md, schedule regular diagnostics
// - environment-check: Run popebot_doctor_check every hour
// - skills-health: Run popebot_doctor_run({ categories: ["skills"] }) daily

With multi-agent-orchestrator

Delegate diagnostics to specialized agents:

parallel_delegates({
  tasks: [
    { agent: "api-tester", task: "Check all API endpoints" },
    { agent: "skill-doctor", task: "Verify skill health" }
  ]
})

Performance

Metric	Expected
Full diagnostic run	2-5 seconds
Quick check	<1 second
Skills check only	1-2 seconds
API connectivity	1-3 seconds
Report generation	<1 second

Error Handling

Network failures: Categorized as errors, suggest checking connectivity
Permission issues: Reported as warnings with remediation steps
Missing tools: Reported as errors with installation guidance
Parse failures: Reported as errors with line numbers
Timeouts: Categorized as errors, suggest retry

Future Enhancements

Web dashboard for visual diagnostics
Historical health tracking over time
Performance benchmarking
Dependency vulnerability scanning
Integration with telemetry systems
Predictive failure detection
Automated health alerts

Inspiration

This skill is adapted from:

ZeroClaw's Doctor: Diagnostic architecture and severity levels
OpenClaw's Health Checks: API connectivity patterns
Kubernetes Health Probes: Checking philosophy

License

MIT - See repository LICENSE file