docs: Update code review documentation with PR review workflow

openhands/usage/essential-guidelines/when-to-use-openhands.mdx

@@ -0,0 +1,282 @@
+---
+title: TODO-When to Use OpenHands
+description: Guidance on when OpenHands is the right tool for your task
+---
+
+OpenHands excels at many development tasks, but knowing when to use it—and when to handle things yourself—helps you get the best results. This guide helps you identify the right tasks for OpenHands and set yourself up for success.
+
+## Task Complexity Guidance
+
+### Simple Tasks
+
+**Ideal for OpenHands** — These tasks can often be completed in a single session with minimal guidance.
+
+- Adding a new function or method
+- Writing unit tests for existing code
+- Fixing simple bugs with clear error messages
+- Code formatting and style fixes
+- Adding documentation or comments
+- Simple refactoring (rename, extract method)
+- Configuration changes
+
+**Example prompt:**
+```
+Add a calculateDiscount() function to src/utils/pricing.js that takes 
+a price and discount percentage, returns the discounted price. 
+Add unit tests.
+```
+
+### Medium Complexity Tasks
+
+**Good for OpenHands** — These tasks may need more context and possibly some iteration.
+
+- Implementing a new API endpoint
+- Adding a feature to an existing module
+- Debugging issues that span multiple files
+- Migrating code to a new pattern
+- Writing integration tests
+- Performance optimization with clear metrics
+- Setting up CI/CD workflows
+
+**Example prompt:**
+```
+Add a user profile endpoint to our API:
+- GET /api/users/:id/profile
+- Return user data with their recent activity
+- Follow patterns in existing controllers
+- Add integration tests
+- Handle not-found and unauthorized cases
+```
+
+### Complex Tasks
+
+**May require iteration** — These benefit from breaking down into smaller pieces.
+
+- Large refactoring across many files
+- Architectural changes
+- Implementing complex business logic
+- Multi-service integrations
+- Performance optimization without clear cause
+- Security audits
+- Framework or major dependency upgrades
+
+**Recommended approach:**
+```
+Break large tasks into phases:
+
+Phase 1: "Analyze the current authentication system and document 
+all touch points that need to change for OAuth2 migration."
+
+Phase 2: "Implement the OAuth2 provider configuration and basic 
+token flow, keeping existing auth working in parallel."
+
+Phase 3: "Migrate the user login flow to use OAuth2, maintaining 
+backwards compatibility."
+```
+
+## Best Use Cases
+
+### Ideal Scenarios
+
+OpenHands is **most effective** when:
+
+| Scenario | Why It Works |
+|----------|--------------|
+| Clear requirements | OpenHands can work independently |
+| Well-defined scope | Less ambiguity, fewer iterations |
+| Existing patterns to follow | Consistency with codebase |
+| Good test coverage | Easy to verify changes |
+| Isolated changes | Lower risk of side effects |
+
+**Perfect use cases:**
+
+- **Bug fixes with reproduction steps**: Clear problem, measurable solution
+- **Test additions**: Existing code provides the specification
+- **Documentation**: Code is the source of truth
+- **Boilerplate generation**: Follows established patterns
+- **Code review and analysis**: Read-only, analytical tasks
+
+### Good Fit Scenarios
+
+OpenHands works **well with some guidance** for:
+
+- **Feature implementation**: When requirements are documented
+- **Refactoring**: When goals and constraints are clear
+- **Debugging**: When you can provide logs and context
+- **Code modernization**: When patterns are established
+- **API development**: When specs exist
+
+**Tips for these scenarios:**
+
+1. Provide clear acceptance criteria
+2. Point to examples of similar work in the codebase
+3. Specify constraints and non-goals
+4. Be ready to iterate and clarify
+
+### Poor Fit Scenarios
+
+**Consider alternatives** when:
+
+| Scenario | Challenge | Alternative |
+|----------|-----------|-------------|
+| Vague requirements | Unclear what "done" means | Define requirements first |
+| Exploratory work | Need human creativity/intuition | Brainstorm first, then implement |
+| Highly sensitive code | Risk tolerance is zero | Human review essential |
+| Organizational knowledge | Needs tribal knowledge | Pair with domain expert |
+| Visual design | Subjective aesthetic judgments | Use design tools |
+
+**Red flags that a task may not be suitable:**
+
+- "Make it look better" (subjective)
+- "Figure out what's wrong" (too vague)
+- "Rewrite everything" (too large)
+- "Do what makes sense" (unclear requirements)
+- Changes to production infrastructure without review
+
+## Limitations
+
+### Current Limitations
+
+Be aware of these constraints:
+
+- **Long-running processes**: Sessions have time limits
+- **Interactive debugging**: Can't set breakpoints interactively
+- **Visual verification**: Can't see rendered UI easily
+- **External system access**: May need credentials configured
+- **Large codebase analysis**: Memory and time constraints
+
+### Technical Constraints
+
+| Constraint | Impact | Workaround |
+|------------|--------|------------|
+| Session duration | Very long tasks may timeout | Break into smaller tasks |
+| Context window | Can't see entire large codebase at once | Focus on relevant files |
+| No persistent state | Previous sessions not remembered | Use AGENTS.md for context |
+| Network access | Some external services may be blocked | Use local resources when possible |
+
+### Scope Boundaries
+
+OpenHands works within your codebase but has boundaries:
+
+**Can do:**
+- Read and write files in the repository
+- Run tests and commands
+- Access configured services and APIs
+- Browse documentation and reference material
+
+**Cannot do:**
+- Access your local environment outside the sandbox
+- Make decisions requiring business context it doesn't have
+- Replace human judgment for critical decisions
+- Guarantee production-safe changes without review
+
+## Pre-Task Checklist
+
+### Prerequisites
+
+Before starting a task, ensure:
+
+- [ ] Clear description of what you want
+- [ ] Expected outcome is defined
+- [ ] Relevant files are identified
+- [ ] Dependencies are available
+- [ ] Tests can be run
+
+### Environment Setup
+
+Prepare your repository:
+
+```markdown
+## AGENTS.md Checklist
+
+- [ ] Build commands documented
+- [ ] Test commands documented  
+- [ ] Code style guidelines noted
+- [ ] Architecture overview included
+- [ ] Common patterns described
+```
+
+See [Repository Setup](/openhands/usage/customization/repository) for details.
+
+### Repository Preparation
+
+Optimize for success:
+
+1. **Clean state**: Commit or stash uncommitted changes
+2. **Working build**: Ensure the project builds
+3. **Passing tests**: Start from a green state
+4. **Updated dependencies**: Resolve any dependency issues
+5. **Clear documentation**: Update AGENTS.md if needed
+
+## Post-Task Review
+
+### Quality Checks
+
+After OpenHands completes a task:
+
+- [ ] Review all changed files
+- [ ] Understand each change made
+- [ ] Check for unintended modifications
+- [ ] Verify code style consistency
+- [ ] Look for hardcoded values or credentials
+
+### Validation Steps
+
+1. **Run tests**: `npm test`, `pytest`, etc.
+2. **Check linting**: Ensure style compliance
+3. **Build the project**: Verify it still compiles
+4. **Manual testing**: Test the feature yourself
+5. **Edge cases**: Try unusual inputs
+
+### Learning from Results
+
+After each significant task:
+
+**What went well?**
+- Note effective prompt patterns
+- Document successful approaches
+- Update AGENTS.md with learnings
+
+**What could improve?**
+- Identify unclear instructions
+- Note missing context
+- Plan better for next time
+
+**Update your repository:**
+```markdown
+## Things OpenHands Should Know (add to AGENTS.md)
+
+- When adding API endpoints, always add to routes/index.js
+- Our date format is ISO 8601 everywhere
+- All database queries go through the repository pattern
+```
+
+## Decision Framework
+
+Use this framework to decide if a task is right for OpenHands:
+
+```
+Is the task well-defined?
+├── No → Define it better first
+└── Yes → Continue
+
+Do you have clear success criteria?
+├── No → Define acceptance criteria
+└── Yes → Continue
+
+Is the scope manageable (< 100 LOC)?
+├── No → Break into smaller tasks
+└── Yes → Continue
+
+Do examples exist in the codebase?
+├── No → Provide examples or patterns
+└── Yes → Continue
+
+Can you verify the result?
+├── No → Add tests or verification steps
+└── Yes → ✅ Good candidate for OpenHands
+```
+
+<Note>
+When in doubt, start small. A focused task that succeeds builds confidence for larger tasks. You can always iterate and expand scope based on results.
+</Note>