| name | draft_troubleshooting |
| description | Draft a new troubleshooting documentation page or update an existing one. Use for known issues, common errors, and diagnostic guides. Troubleshooting pages follow a problem → cause → solution format, leading with the symptom the user sees. |
Draft troubleshooting page
Draft a troubleshooting page that helps users diagnose and fix common issues.
Workflow
Follow the workflow in .agents/skills/draft_docs/SKILL.md, using the troubleshooting template at .agents/templates/troubleshooting.md.
Frontmatter description
One sentence, 50-160 characters, naming the symptoms covered rather than the act of troubleshooting.
- ✅
Fix sign-in failures, failed conversation resumes, and update problems in the Warp Agent CLI.
- ❌
Troubleshooting information for common problems.
See "Descriptions by content type" under Frontmatter in AGENTS.md for the full rules.
Content type rules
These rules are specific to troubleshooting pages (from the "Drafting by content type" section of AGENTS.md):
- Use the problem or error message as the header — this helps with search.
- Group related issues under broader category headers (e.g., "SSH", "Shells").
- Lead with the symptom — the reader arrived because something broke. Don't make them read context before getting to the fix.
- Provide workarounds when a fix isn't available.
- Link to related troubleshooting pages and support channels.
- Include workarounds even when no fix exists — documenting a known issue without a workaround still saves the user time searching.
- Title convention: "Troubleshooting [feature]" or "Error: [error name]"
- Apply the tone rules in AGENTS.md → Voice & tone: lead with the fix, not framing; no marketing buzzwords or meta-openers. Delete any category or symptom section you don't have real content for — a short page is a finished page.
Heading case
All headings (H1–H4) must use sentence case: capitalize only the first word and proper feature names.
- ✅
# Troubleshooting environments
- ✅
## Agent fails to start
- ❌
# Troubleshooting Environments
- ❌
## Agent Fails To Start
Existing examples
Read 2-3 of these strong examples to match the existing pattern:
src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdsrc/content/docs/reference/cli/troubleshooting.md
