[Advanced]: Prompt Coderabbit on how to review /docs

[exploreriii]

🧠 Advanced Contributors

This issue is intended for contributors who are already very familiar with the
Hiero Python SDK codebase and its architectural patterns.

You should feel comfortable:

• navigating multiple modules across src/
• understanding and modifying core SDK abstractions
• reasoning about API design and backwards compatibility
• updating or extending tests, examples, and documentation as needed
• making changes that may affect public-facing behavior

New developers should start with
Good First Issues or Intermediate Issues first.

🐞 Problem Description

Coderabbit can have custom settings and prompts, telling it exactly how to review certain paths in the code.

We can trial this feature out with /docs.

💡 Proposed / Expected Solution

We can create an /docs configuration for code rabbit that makes code rabbit commiter or maintainer-level preliminary reviewer, for /docs.

Please note we have:
/docs (general)
/docs/sdk_users (user facing docs)
/docs/sdk_developers (developer facing docs, like tutorials)

Organisation is not yet super great, and the docs are still a WIP

🧠 Implementation & Design Notes

To do this, extend:

.coderabbit.yaml

Read examples and config to research what we might want (you'll need to be an original thinker here with full creative ability)
https://docs.coderabbit.ai/reference/configuration
https://github.com/coderabbitai/awesome-coderabbit/blob/main/configs/python/coderabbit-python-portal.yaml
https://github.com/coderabbitai/awesome-coderabbit/tree/main/configs/python

Here are SOME ideas I have, but this is just a rough guide and only a starting point:

path_instructions:

• path: "docs/**"

• represent general documentation for both sdk users and sdk developers

• Focus on correctness, clarity, and usefulness, not detail.

• Consider whether missing explanations in a pull request should be additions to that PR or a new issue raised

• Avoid suggesting large-scale restructures unless a problem blocks understanding.

• Check URls if possible

  • path: "docs/sdk_users/**"
    instructions: >-
    -These documents are user facing guidelines intended for
    developers consuming the SDK.

• Assume readers have some development experience but may be totally new new to this SDK.

• Do not assume any knowledge of how to use the sdk

• Do not assume any knowledge of how the sdk was constructed, nor desire

• The user just wants to learn how to use the sdk

• Explanations must be concrete, actionable, and unambiguous.

• Steps should be explicit and ordered.

• Ensure snippets are correct, complete, and up to date.

  • path: "docs/sdk_developers/**"
    instructions: >-

• These documents are developer-facing and may include tutorials,
  architectural explanations, or contribution guidance.

• Assume some readers may be total beginners yet some experts

• Assume intent to extend, debug, or contribute to the SDK.

✅ Acceptance Criteria

To merge this issue, the pull request must:

• Fully address the problem and design goals described above
• Maintain backwards compatibility unless explicitly approved otherwise
• Follow existing architectural and coding conventions
• Include comprehensive tests covering new and existing behavior
• Update relevant examples and documentation
• Pass all CI checks
• Include a valid changelog entry
• Use DCO and GPG-signed commits

📚 Additional Context, Links, or Prior Art

Optional.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• [Advanced]: Prompt Coderabbit on how to review /examples #1180
• [Good First Issue]: Create docs/maintainers/good_first_issues.md #1034
• Expand Contributing.md Documentation explainer section #431
• Move examples/sdk_developers/common_issues.md to docs/sdk_developers/common_issues.md #516

🔗 Related PRs

#1128 - docs: add GFI-Guidelines Doc File [merged]
#1133 - docs: gfi guidelines [merged]
#1162 - chore: move helpful references to additional context [merged]
#1173 - feat(ci): add workflow to remind pull requests to link issues [merged]
#1174 - ci: coderabbit yaml [merged]

👤 Suggested Assignees

• exploreriii
• aceppaluni
• andrerovee
• undefinedIsMyLife

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Configure CodeRabbit with path-specific review instructions for the documentation directory to enable maintainer-level automated documentation reviews across three documentation areas: general docs, user-facing SDK guides, and developer tutorials.

Observations

Codebase Summary

The Hiero Python SDK is an open-source project with comprehensive documentation organized into multiple sections: user-facing guides (docs/sdk_users/), developer workflows and training materials (docs/sdk_developers/), Good First Issue documentation (docs/GFI/), maintainer guidelines (docs/maintainers/), and community resources. The project uses a .coderabbit.yaml configuration file with an assertive review profile that minimizes noise. Documentation follows established conventions including DCO/GPG signing requirements, changelog entries, and specific formatting standards with numbered tutorials, emoji indicators, and structured table of contents sections.

Assumptions

Assumption 1: Level of specificity for path instructions

Options Considered:

• Generic instructions applicable to all documentation
• Three moderately detailed path configurations matching the ticket structure
• Six or more highly specific paths including separate instructions for training, GFI, and maintainer docs

Chosen Option: Three moderately detailed path configurations (docs/**, docs/sdk_users/**, docs/sdk_developers/**) that balance the trial nature of this feature with meaningful value. This aligns with the ticket's suggested structure while incorporating insights from actual documentation patterns discovered during exploration. More granular paths (training, GFI, maintainers) can be added later if the trial proves successful.

Rationale: This aligns with the ticket's suggested structure while incorporating insights from actual documentation patterns discovered during exploration. More granular paths (training, GFI, maintainers) can be added later if the trial proves successful.

Assumption 2: Depth of documentation standards enforcement

Options Considered:

• Focus solely on writing quality (clarity, grammar, structure)
• Include both writing quality and reference to documented standards
• Enforce strict compliance checks for all documented conventions

Chosen Option: Include both writing quality and references to key documented standards. This provides more useful reviews than generic writing feedback while avoiding overly rigid enforcement that might frustrate contributors. Instructions will prompt CodeRabbit to check for common issues like broken links, incomplete setup steps, and consistency with documented workflows, without creating an exhaustive checklist.

Rationale: This provides more useful reviews than generic writing feedback while avoiding overly rigid enforcement that might frustrate contributors. Instructions will prompt CodeRabbit to check for common issues like broken links, incomplete setup steps, and consistency with documented workflows, without creating an exhaustive checklist.

Assumption 3: Handling of code examples and snippets in documentation

Options Considered:

• Ignore code examples, focus only on prose
• Treat code examples equally to prose documentation
• Prioritize code correctness and completeness in examples

Chosen Option: Prioritize code correctness and completeness in examples, especially for user-facing docs. This ensures that developers copying examples from documentation have working, complete code. Instructions will specifically call out validation of code snippets, imports, and runnable examples.

Rationale: This ensures that developers copying examples from documentation have working, complete code. Instructions will specifically call out validation of code snippets, imports, and runnable examples.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Add Path-Specific Documentation Review Configuration

This phase extends the existing .coderabbit.yaml file with a new path_instructions section that provides tailored review guidance for documentation. The configuration will leverage CodeRabbit's minimatch glob pattern matching to apply different review criteria based on documentation audience and purpose.

Task 1: Add path_instructions section to .coderabbit.yaml

Create a new top-level path_instructions section (note: this goes under reviews: based on CodeRabbit schema) with three path configurations that provide context-aware review instructions.

• Add path_instructions: as a new property under the reviews: section in .coderabbit.yaml
• Position this section after existing review configuration properties to maintain logical grouping
• Use YAML list syntax with each path entry containing path and instructions fields
• Ensure proper indentation aligns with existing configuration structure (2-space indentation)

Task 2: Configure general documentation review instructions (docs/**)

Define review instructions for the general documentation path that apply baseline quality standards across all documentation files.

• Create path entry with glob pattern "docs/**" to match all documentation files
• Include instructions focused on correctness, clarity, and usefulness without excessive detail
• Guide reviewer to check for broken URLs and invalid links
• Prompt consideration of whether missing information should be addressed in current PR or raised as separate issue
• Discourage large-scale restructure suggestions unless clarity is blocked
• Emphasize practical, actionable feedback over theoretical improvements

Task 3: Configure SDK user documentation review instructions (docs/sdk_users/**)

Define review instructions tailored for end-user facing documentation that assumes readers are new to the SDK.

• Create path entry with glob pattern "docs/sdk_users/**" for user-facing guides
• Emphasize that readers have general development experience but are new to this specific SDK
• Instruct reviewer not to assume any prior SDK usage knowledge or internal implementation understanding
• Focus on concrete, actionable, unambiguous explanations with explicit ordered steps
• Prioritize correctness and completeness of code examples and snippets
• Ensure code examples include all necessary imports and are runnable without modification
• Check that setup instructions are complete and don't skip assumed knowledge steps

Task 4: Configure SDK developer documentation review instructions (docs/sdk_developers/**)

Define review instructions for developer-facing documentation covering tutorials, architecture, and contribution workflows.

• Create path entry with glob pattern "docs/sdk_developers/**" for contributor documentation
• Account for audience range from total beginners to expert contributors
• Assume reader intent to extend, debug, or contribute to the SDK codebase
• Reference key documented standards: DCO/GPG signing requirements, changelog entry conventions, one issue per PR policy
• For tutorial content (particularly in training/ subdirectories), verify logical progression and completeness
• Check that contribution workflows accurately reflect actual required steps (signing, testing, linting)
• Validate that architectural explanations provide sufficient context for code modifications
• Ensure consistency with established conventions (conventional commits, numbered tutorials, emoji indicators)

🤖 Prompt for AI agents

Extend the `.coderabbit.yaml` configuration with path-specific documentation
review instructions.

Add a `path_instructions` property under the `reviews:` section with three path
configurations:

1. For `docs/**` (general documentation):
   - Check correctness, clarity, and usefulness
   - Validate links and URLs
   - Provide practical, actionable feedback
   - Consider whether issues should be addressed now or raised separately

2. For `docs/sdk_users/**` (user-facing guides):
   - Assume readers are new to the SDK but have general dev experience
   - Require concrete, actionable explanations with explicit steps
- Validate code examples for correctness and completeness (imports, runnability)
   - Ensure setup instructions are complete without assumed knowledge

3. For `docs/sdk_developers/**` (contributor documentation):
   - Address audience from beginners to experts wanting to contribute
- Reference standards: DCO/GPG signing, changelog conventions, one issue per PR
   - Verify tutorial logical progression and completeness
   - Validate contribution workflows match actual requirements
- Check consistency with conventions (conventional commits, numbered tutorials,
emoji indicators)

Use proper YAML formatting with 2-space indentation and list syntax for path
entries.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Extend the `.coderabbit.yaml` configuration with path-specific documentation
review instructions.

Add a `path_instructions` property under the `reviews:` section with three path
configurations:

1. For `docs/**` (general documentation):
   - Check correctness, clarity, and usefulness
   - Validate links and URLs
   - Provide practical, actionable feedback
   - Consider whether issues should be addressed now or raised separately

2. For `docs/sdk_users/**` (user-facing guides):
   - Assume readers are new to the SDK but have general dev experience
   - Require concrete, actionable explanations with explicit steps
- Validate code examples for correctness and completeness (imports, runnability)
   - Ensure setup instructions are complete without assumed knowledge

3. For `docs/sdk_developers/**` (contributor documentation):
   - Address audience from beginners to experts wanting to contribute
- Reference standards: DCO/GPG signing, changelog conventions, one issue per PR
   - Verify tutorial logical progression and completeness
   - Validate contribution workflows match actual requirements
- Check consistency with conventions (conventional commits, numbered tutorials,
emoji indicators)

Use proper YAML formatting with 2-space indentation and list syntax for path
entries.

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!

[exploreriii]

Reopening as an imterdiate issue as we now have other examples to leverage