coderabbitai · alexcoderabbitai · Apr 8, 2025 · Apr 8, 2025 · Apr 8, 2025 · Apr 8, 2025
diff --git a/docs/guides/agent_chat.md b/docs/guides/agent_chat.md
@@ -2,7 +2,7 @@
 title: Chat and Agentic Chat
 sidebar_label: Chat and Agentic Chat
 description: Learn about CodeRabbit Pro's chat and agentic chat system
-sidebar_position: 8
+sidebar_position: 3
 ---
 
 # CodeRabbit Chat

diff --git a/docs/guides/commands.md b/docs/guides/commands.md
@@ -1,3 +1,10 @@
+---
+title: Commands
+sidebar_label: Commands
+description: Learn how to control CodeRabbit using commands in pull request comments
+sidebar_position: 1
+---
+
 # CodeRabbit Commands
 
 > Control your code reviews directly from pull request comments using CodeRabbit's command system. Each command starts with `@coderabbitai` followed by the specific action you want to take.

diff --git a/docs/guides/custom-reports.md b/docs/guides/custom-reports.md
@@ -2,7 +2,7 @@
 title: Custom Reports
 sidebar_label: Custom Reports
 description: Learn how to create custom reports with CodeRabbit Pro's flexible reporting system
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 ```mdx-code-block

diff --git a/docs/guides/issue-chat.md b/docs/guides/issue-chat.md
@@ -2,7 +2,7 @@
 title: Issue Chat
 sidebar_label: Issue Chat
 description: Learn how to use CodeRabbit's chat capabilities within issues
-sidebar_position: 10
+sidebar_position: 4
 ---
 
 ```mdx-code-block

diff --git a/docs/guides/issue-creation.md b/docs/guides/issue-creation.md
@@ -2,7 +2,7 @@
 title: Issue Creation
 sidebar_label: Issue Creation
 description: Learn how to create issues directly through CodeRabbit
-sidebar_position: 9
+sidebar_position: 5
 ---
 
 ```mdx-code-block

diff --git a/docs/guides/linked-issues.md b/docs/guides/linked-issues.md
@@ -0,0 +1,175 @@
+---
+title: Linked Issues
+sidebar_label: Linked Issues
+description: Learn how to effectively use linked issues with CodeRabbit for better pull request assessments
+sidebar_position: 6
+---
+
+# Linked Issues
+
+CodeRabbit provides intelligent assessment of linked issues to validate whether pull requests properly address their requirements. This guide explains how to effectively use linked issues and write clear issue descriptions for optimal results.
+
+## Understanding Linked Issues
+
+A linked issue is one that is explicitly referenced in your pull request description using platform-specific syntax:
+
+- GitHub: `fixes #123`, `closes #123`, `resolves #123`
+- GitLab: `closes #123`, `fixes #123`, or full URLs
+- Jira/Linear: Full URLs to tickets
+
+When CodeRabbit detects linked issues, it analyzes them against your pull request changes to determine if the requirements are met:
+
+![Linked Issue Assessment Example](/img/guides/linked-issue.png)
+
+## Best Practices for Issue Writing
+
+### Issue Titles
+
+Create descriptive, technical titles that clearly state the goal:
+
+✅ Good Examples:
+
+- "Add PrismaLint integration to configuration flow"
+- "Fix race condition in user authentication"
+- "Implement caching for GraphQL queries"
+
+❌ Poor Examples:
+
+- "Fix bug"
+- "Update code"
+- "Improve performance"
+
+### Issue Descriptions
+
+Write comprehensive descriptions that provide clear technical context:
+
+1. **Problem Statement**
+
+   - Clearly describe what needs to be changed
+   - Include technical details about affected components
+   - Reference specific files or functions if known
+
+2. **Expected Solution**
+   - Outline the desired implementation approach
+   - Include code examples or pseudo-code when relevant
+   - List specific acceptance criteria
+
+Example Description:
+
+```markdown
+Problem:
+The configuration system doesn't validate Prisma schema files before deployment,
+leading to potential runtime errors.
+
+Solution:
+Integrate PrismaLint into the configuration flow to:
+
+- Validate schema files during PR checks
+- Enforce consistent naming conventions
+- Prevent common Prisma anti-patterns
+
+Affected Components:
+
+- Configuration validation pipeline
+- CI/CD workflow
+- Schema validation logic
+
+Acceptance Criteria:
+
+- [ ] PrismaLint runs on all PR checks
+- [ ] Failed validations block merging
+- [ ] Clear error messages for schema issues
+```
+
+### Consistent Terminology
+
+Use consistent terminology between issues and pull requests:
+
+✅ Good:
+
+- Use the same technical terms consistently
+- Reference components with their exact names
+- Maintain consistent naming patterns
+
+❌ Poor:
+
+- Mixing different terms for the same component
+- Using vague or non-technical language
+- Inconsistent capitalization or formatting
+
+## Linking Issues Effectively
+
+### In Pull Requests
+
+1. **Direct References**
+
+   ```markdown
+   Fixes #123
+   Resolves organization/repo#456
+   Closes https://github.com/org/repo/issues/789
+   ```
+
+2. **Multiple Issues**
+
+   ```markdown
+   This PR addresses:
+
+   - Fixes #123
+   - Closes #456
+   - Resolves https://jira.company.com/browse/PROJ-789
+   ```
+
+### Cross-References
+
+For better traceability:
+
+1. Add PR references in issue comments
+2. Use complete URLs when linking external systems
+3. Maintain bidirectional links between related issues
+
+## How CodeRabbit Assesses Linked Issues
+
+CodeRabbit evaluates linked issues by:
+
+1. Analyzing issue titles and descriptions
+2. Comparing changes in the pull request
+3. Validating if requirements are met
+4. Providing an assessment with:
+   - ✅: If the objective has been addressed in the PR. The 'Explanation' column will be left blank.
+   - ❌: If the objective has not been addressed in the PR. Here a brief explanation is added to the 'Explanation' column.
+   - ❓: If it is unclear whether the objective has been addressed. Here a brief explanation is added to the 'Explanation' column.
+
+:::note
+Only the issue title and description are considered in the assessment. Comments and discussion threads are not currently analyzed.
+:::
+
+## Tips for Better Assessments
+
+1. **Be Specific**
+
+   - Include clear, measurable objectives
+   - List specific technical requirements
+   - Reference affected code components
+
+2. **Provide Context**
+
+   - Explain why changes are needed
+   - Document current behavior
+   - Describe expected outcomes
+
+3. **Use Technical Details**
+
+   - Include file paths when known
+   - Reference specific functions or classes
+   - Mention relevant technologies
+
+4. **Keep It Focused**
+   - One main objective per issue
+   - Clear scope boundaries
+   - Specific acceptance criteria
+
+## Related Resources
+
+- [Review Instructions](./review-instructions.md)
+- [Issue Chat](./issue-chat.md)
+- [Issue Creation](./issue-creation.md)
diff --git a/docs/guides/ondemand-reports.md b/docs/guides/ondemand-reports.md
@@ -2,7 +2,7 @@
 title: On-demand Reports
 sidebar_label: On-demand Reports
 description: CodeRabbit offers a way to generate on-demand reports using a simple API request
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 ```mdx-code-block

diff --git a/docs/guides/review-instructions.md b/docs/guides/review-instructions.md
@@ -5,7 +5,7 @@ description:
   CodeRabbit offers various customization options to tailor the reviews to your
   specific requirements. Customizations can be made using one of the below
   options.
-sidebar_position: 3
+sidebar_position: 2
 ---
 
 The guide explains how to add custom review instructions for the entire project.

diff --git a/docs/guides/scheduled-reports.md b/docs/guides/scheduled-reports.md
@@ -2,7 +2,7 @@
 title: Scheduled Reports
 sidebar_label: Scheduled Reports
 description: Learn how to set up automated recurring reports with CodeRabbit Pro
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 ```mdx-code-block

diff --git a/static/img/guides/linked-issue.png b/static/img/guides/linked-issue.png