[task] Convert guides to task-oriented how-to documentation #1453

Objective

Transform existing guides into clear, task-oriented how-to documentation that shows users how to solve specific problems.

Context

The scout report identifies that current "Guides" and "Application Areas" overlap in purpose. Diátaxis recommends how-to guides be focused on solving specific tasks, with clear prerequisites and outcomes.

Approach

1. Audit existing guides in docs/src/content/docs/guides/ and map to specific tasks
2. Rewrite guides to follow how-to structure:
   • Clear task statement (e.g., "How to configure network permissions")
   • Prerequisites listed upfront
   • Step-by-step instructions
   • Expected outcome/verification step
3. Move content to docs/src/content/docs/how-to/ directory
4. Ensure each guide addresses a single task

Example how-to topics:

• How to debug workflow failures
• How to configure safe outputs for issue creation
• How to use custom MCP servers
• How to restrict network access
• How to implement ChatOps bots
• How to handle workflow permissions

Files to Modify/Create

• Migrate: Content from docs/src/content/docs/guides/ to docs/src/content/docs/how-to/
• Create: docs/src/content/docs/how-to/debug-workflows.md
• Create: docs/src/content/docs/how-to/configure-safe-outputs.md
• Update: Existing guides to follow task-oriented structure
• Update: Cross-references in other documentation pages

Acceptance Criteria

• Each how-to guide addresses a single, specific task
• Prerequisites are clearly stated at the beginning
• Step-by-step instructions are actionable and clear
• Expected outcomes are described
• No overlap between different how-to guides
• All internal links are updated to new locations

Related to

Issue #1433
Related to #1433

AI generated by Plan Command