doc(devbird): Add some docs

[kdy1]

No description provided.

[Copilot]

Pull Request Overview

This PR enhances the DevBird documentation by clarifying three common user questions: single-node task graphs, concurrent PR handling, and workflow execution security.

• Added explanation that single-node task graphs are normal for simple tasks
• Documented expected behavior for multiple concurrent PRs
• Clarified that workflows always execute on the main branch for security reasons

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
devbird/tasks/composite/index.mdx	Added Note explaining that simple tasks can legitimately have single-node task graphs
devbird/reviewing-prs/index.mdx	Added section documenting that multiple concurrent PRs are expected behavior
devbird/getting-started/github-workflow.mdx	Added section explaining the security design where workflows always run on main branch

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[claude]

PR Review: Documentation Improvements

Thanks for these documentation additions! Overall, these are helpful clarifications that address common user questions. Here's my detailed feedback:

✅ Strengths

1. Good Information Architecture: All three additions address real user pain points and confusion
2. Proper Frontmatter: All files have required title and description fields
3. Consistent Voice: Uses second-person voice ("you") as required
4. Relative Links: Internal links use proper relative paths
5. Mintlify Components: Appropriate use of <Info> and <Note> components

📝 Content Quality Feedback

devbird/getting-started/github-workflow.mdx

New Section: "Understanding workflow execution"

✅ Good:

• Addresses a common source of confusion (why workflows show "main" branch)
• Security rationale is clearly explained
• Distinguishes between workflow execution location and base_branch parameter

⚠️ Suggestions:

1. Clarity improvement: The phrase "workflow execution itself always happens on the default branch" could be more precise. Consider: "the workflow file (.github/workflows/devbird.yml) is always read from your default branch"
2. User mental model: Consider adding a practical example showing what this means for users (e.g., "If you modify devbird.yml in a PR, those changes won't take effect until the PR is merged to main")
3. Link consistency: The section ends with a "Next steps" that links to first-pr - this is good as it matches existing style

devbird/reviewing-prs/index.mdx

New Section: "Multiple concurrent PRs"

✅ Good:

• Concise and directly addresses user expectations
• Bullet format is scannable
• Reassuring tone ("This is expected behavior")

⚠️ Suggestions:

1. Add context: This section appears between "Ready for Merge" and "PR comments" - consider if this placement is logical or if it should be moved earlier (perhaps after "The automated PR workflow")?
2. Link to composite tasks: Since composite tasks commonly create multiple PRs, consider adding a cross-reference like: "This is especially common with Composite Tasks"
3. Edge cases: Consider mentioning any limitations (e.g., rate limits, GitHub API constraints)

devbird/tasks/composite/index.mdx

New Note: "Simple tasks can have a single node"

✅ Good:

• Prevents user confusion when they see a single-node graph
• Positioned perfectly right after explaining task graph creation
• Reassuring language

⚠️ Minor suggestion:

• Consider rephrasing slightly for clarity: "For straightforward requests that don't need to be broken down..." instead of "don't require breaking down"

🔍 Quality Assurance Checks

Writing Standards

• ✅ Second-person voice ("you") used correctly
• ✅ No untested code examples (none added)
• ✅ Alt text not applicable (no images added)
• ✅ Language tags not applicable (no code blocks added)

Formatting & Consistency

• ✅ Matches style of existing pages
• ✅ Proper heading hierarchy
• ✅ Consistent bullet formatting
• ✅ Appropriate use of bold text

Technical Accuracy

• ✅ Security explanation is technically correct
• ✅ GitHub Actions behavior accurately described
• ✅ No misleading statements detected

🔒 Security Review

• ✅ No security concerns
• ✅ Security rationale properly explained (workflow execution)
• ✅ No credential exposure

🧪 Testing & Validation

Since these are documentation updates with no code:

• ✅ Frontmatter is valid YAML
• ✅ Links are relative and properly formatted
• ⚠️ Recommendation: Verify internal links resolve correctly after merge

📊 Content Strategy Alignment

Following project instructions from CLAUDE.md:

✅ Adheres to:

• "Document just enough for user success"
• "Prioritize accuracy and usability"
• "Check existing patterns for consistency"
• "Start by making the smallest reasonable changes"

⚠️ Consider:

• "Search for existing information before adding new content" - The multiple concurrent PRs concept might already be mentioned elsewhere in composite task docs (didn't find duplication, but worth double-checking)

🎯 Final Recommendation

APPROVE with minor suggestions

These additions are valuable and ready to merge. The suggestions above are minor improvements for clarity and user experience, but nothing blocking.

Priority Actions (Optional):

1. Consider the placement of "Multiple concurrent PRs" section
2. Add cross-reference to composite tasks in the concurrent PRs section
3. Review if workflow execution explanation could be simplified

Before Merge:

• ✅ No blocking issues
• ✅ Ready to merge as-is
• 📝 Suggestions are optional enhancements

---

Great work on identifying these documentation gaps! These clarifications will help users understand DevBird's behavior better.