Documentation: Missing troubleshooting guide for common task failures

🤖 Axon Agent @gjkim42

Problem

When following the Quick Start, new users will inevitably encounter task failures (wrong credentials, network issues, git auth problems, etc.). Currently, the README provides minimal debugging guidance:

• Line 133-134 mentions checking controller logs: kubectl logs deployment/axon-controller-manager -n axon-system
• No guidance on checking task pod logs
• No explanation of common failure modes
• No step-by-step debugging workflow

The self-development README has a "Troubleshooting" section (lines 223-239), but this isn't discoverable from the main README and is specific to TaskSpawner scenarios.

User Impact

First-time users hit a wall when their task fails:

• README says "Run your first task" but doesn't explain what to do when it fails
• Common errors (bad credentials, git auth, network issues) aren't documented
• Users don't know whether to check task logs, controller logs, or both
• No clear progression: "check X, if that doesn't help, check Y"

Proposed Solution

Add a "Troubleshooting" section to the main README (after "Quick Start" and before "How It Works") with:

1. How to check task status:

   kubectl get task <name>
   axon logs <name>
   

2. Common failure scenarios:

   • Task stuck in Pending: credential issues, secret not found
   • Task Failed (git clone): auth issues, repo doesn't exist, network
   • Task Failed (agent error): check agent logs, model/API quota exceeded
   • Controller issues: kubectl logs deployment/axon-controller-manager -n axon-system

3. Debugging workflow:

   1. Check task phase: kubectl get task <name>
   2. View task logs: axon logs <name>
   3. If pod not created, check controller logs
   4. For git errors, verify workspace/secret configuration
   

4. Link to detailed troubleshooting:
   Reference the self-development README's troubleshooting section for more scenarios.

Example (Minimal)

Add after line 135 in README.md:

### Troubleshooting

**Check task status:**
\`\`\`bash
kubectl get task <name>
axon logs <name>
\`\`\`

**Common issues:**
- **Task stuck in Pending** — Credential secret not found or misconfigured. Verify: `kubectl get secret axon-credentials`
- **Git clone failed** — Workspace auth issue. Check `GITHUB_TOKEN` in workspace secret.
- **Task failed during execution** — Check agent logs with `axon logs <name>` for API errors or model issues.
- **Pod not created** — Controller issue. Check: `kubectl logs deployment/axon-controller-manager -n axon-system`

See [self-development troubleshooting](self-development/README.md#troubleshooting) for more scenarios.

Why This Matters

1. Reduces friction — Users can self-serve basic debugging instead of asking for help
2. Sets expectations — Normalizes that failures happen and shows how to diagnose them
3. Improves adoption — Users who can debug issues themselves are more likely to continue using Axon
4. Completes Quick Start — The guide currently ends at "run your first task" but doesn't cover what happens when it fails

Alternative: Separate Troubleshooting Doc

Could create docs/troubleshooting.md instead and link from README, but for Quick Start issues, inline guidance is more discoverable.

Start in README.md around the Quick Start section and compare it with the Troubleshooting section in self-development/README.md. Add the proposed task-status commands, common failure guidance, debugging workflow, and link to the detailed section. Done means the main Quick Start explains what to check after a failure and the referenced link works.