[Intermediate]: Create a Prompt to Code Rabbit to Explain to it how to review /docs

[exploreriii]

🧩 Intermediate Contributors

This issue is intended for contributors who already have some familiarity with the
Hiero Python SDK codebase and contribution workflow.

You should feel comfortable:

• navigating existing source code and examples
• understanding SDK concepts without step-by-step guidance
• following the standard PR workflow without additional onboarding

If this is your very first contribution to the project, we recommend starting with a few
Good First Issues before working on this one.

🐞 Problem Description

Coderabbit is our first-review-stage AI reviewer
We seek to prompt code rabbit to reach senior-level feedback, and provide this helpful feedback to every pull request

We've prompted it on how to review /examples and /tests, but not yet /docs.

💡 Expected Solution

Prompt code rabbit on how to review /docs

🧠 Implementation Notes

• Edit .coderabbit.yaml at the project root
• Add custom instructions on how to review /docs

Note our /docs are a work in progress meaning they are not yet perfect, somewhat not perfectly structured or complete. Therefore, it is more important to prompt code rabbit on general PRINCIPLES rather than exact instructions without flexibility.

Helpful resources:
Read our existing prompts at root:
.coderabbit.yaml

Read code rabbit documentation:
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

How our /docs are currently structured:

1. sdk_developers
2. sdk_users

Code rabbit should generally understand docs placed in each file serve slightly different purposes.
for sdk developers, it will be technical, how to develop for the SDK, so is more training based in multple areas like writing examples, source code, tests, etc, as well as following our workflow.

for sdk users, they do not need to know any of the workflow or source code , tests, etc, they just need to clearly understand HOW to USE the sdk. Most likely, they'll spend most of the time studying /examples.

These users have different goals:

sdk developers want to understand how to become a python sdk developer
sdk users want to understand how to use the python sdk as quickly as possible, and as correctly as possible

inside sdk_developers we have /training which will one day become a more structured training scheme. WIP.

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 described above
• Follow existing project conventions and patterns
• Include tests or example updates where appropriate
• Pass all CI checks
• Include a valid changelog entry
• Use DCO and GPG-signed commits

📚 Additional Context or Resources

• SDK Developer Docs
• SDK Developer Training

[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

Possible Duplicates

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

Related Issues

• [Advanced]: Prompt Coderabbit on how to review /examples #1180
• [Advanced]: Prompt code rabbit on how to review tests/unit and tests/integration #1193

🔗 Related PRs

#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]
#1189 - feat: Add custom CodeRabbit instructions for examples [merged]
#1231 - chore: enhance unit and integration test review instructions [merged]

👤 Suggested Assignees

• exploreriii
• andrerovee
• undefinedIsMyLife
• Adityarya11
• MonaaEid

---

🧪 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!

[coderabbitai]

Coding Plan

Approach

Add CodeRabbit review prompts to .coderabbit.yaml for the /docs directory, with differentiated instructions for SDK users (learning to use the SDK) and SDK developers (learning to contribute to the SDK), following existing prompt patterns while emphasizing flexible, principle-based guidance suitable for work-in-progress documentation.

Observations

The Hiero Python SDK project uses CodeRabbit as its AI-powered first-stage reviewer. The .coderabbit.yaml configuration file contains a path_instructions array under reviews that defines specialized review prompts for different directories (examples/**/*, tests/unit/**/*, tests/integration/**/*). These prompts follow a consistent structure: numbered Priority frameworks (1-5), Philosophy sections articulating core principles, CRITICAL PRINCIPLES/AVOID sections for boundaries, and domain-specific technical guidance. The global review profile is set to "assertive" with focused, concise feedback.

The documentation structure includes:

• docs/sdk_users/: 2 files focused on SDK usage (running examples, transaction serialization)
• docs/sdk_developers/: 20+ files covering development workflow, setup, testing, contribution guidelines, plus a /training/ subdirectory with 17 structured onboarding files
• Consistent markdown conventions with numbered training files, code snippets in both fragment and complete formats, and cross-references between docs

Assumptions

Assumption 1: Scope of documentation paths

Options Considered:

• Three-path structure (general + user + developer) as suggested in ticket
• Two-path structure (user + developer only) to reduce redundancy
• Single comprehensive path with audience detection
• Four-path structure adding specialized docs/sdk_developers/training/** prompt

Chosen Option: Three-path structure (general + user + developer) as suggested in ticket

Rationale: This aligns with existing patterns (tests have unit/integration splits), provides maximum clarity for contributors about which guidance applies, balances flexibility (general principles) with specificity (audience-tailored feedback), and matches the ticket's explicit suggestions while maintaining room for future refinement if training materials need specialized treatment.

Assumption 2: Balance between flexibility and specificity

Options Considered:

• Rigid, prescriptive rules enforcing specific structure and completeness
• Highly flexible principle-based guidance that suggests rather than demands
• Hybrid approach with mandatory checks (URLs, code correctness) and flexible suggestions (structure, completeness)

Chosen Option: Hybrid approach with mandatory checks (URLs, code correctness) and flexible suggestions (structure, completeness)

Rationale: This ensures critical issues (broken code snippets, invalid URLs) are caught while allowing reviewers to suggest filing issues for major gaps rather than blocking PRs. This matches the ticket's emphasis on "PRINCIPLES rather than exact instructions" and the existing prompt pattern of having CRITICAL PRINCIPLES alongside prioritized guidance, creating a better developer experience by being helpful without being obstructive.

💡 User Tips

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

Implementation Steps

Phase 1: Add Documentation Review Prompts

Add three new path instruction entries to .coderabbit.yaml following the established pattern from existing examples and tests prompts, with priority-based frameworks and philosophy sections tailored to documentation review needs.

Task 1: Create General Documentation Prompt

Add a docs/** path instruction that sets overarching principles for all documentation reviews.

• Insert new entry in the path_instructions array in .coderabbit.yaml following the existing pattern (path + multi-paragraph instructions)
• Structure with a 5-Priority framework: (1) Correctness of code/commands/links → (2) Clarity and comprehensibility → (3) Completeness of explanations → (4) Consistency with existing docs → (5) Accessibility and navigation
• Include a PHILOSOPHY section emphasizing: "Documentation is work-in-progress. Focus on correctness and clarity over perfection. Suggest filing issues for major gaps rather than demanding immediate fixes in every PR."
• Add CRITICAL PRINCIPLES section covering: validate URLs/links work, ensure code snippets are syntactically correct and up-to-date with SDK, check that steps are executable and produce expected results
• Add AVOID section: avoid demanding large-scale restructures unless current structure actively blocks understanding, avoid linting-style feedback on markdown formatting, avoid suggesting changes to established conventions without clear rationale

Task 2: Create SDK Users Documentation Prompt

Add a docs/sdk_users/** path instruction tailored for end-user SDK consumption documentation.

• Insert new entry in path_instructions array in .coderabbit.yaml after the general docs prompt
• Structure with a 5-Priority framework: (1) Code snippet correctness and completeness → (2) Step-by-step clarity and explicitness → (3) Lack of assumptions about SDK knowledge → (4) Actionable, unambiguous instructions → (5) Real-world applicability
• Include a PHILOSOPHY section: "SDK users want to USE the SDK quickly and correctly. They don't care about SDK internals, development workflows, or contribution processes. Every explanation must be concrete, self-contained, and immediately actionable."
• Add CRITICAL PRINCIPLES: assume zero prior SDK knowledge, verify code examples are complete (imports, initialization, error handling), ensure steps are ordered and explicit, validate that examples match current SDK API patterns
• Add domain-specific guidance: check that SDK import paths are correct (from hiero_sdk_python.X import Y), verify transaction patterns match examples/ directory conventions, ensure error handling is shown where appropriate

Task 3: Create SDK Developers Documentation Prompt

Add a docs/sdk_developers/** path instruction tailored for contributor onboarding and development workflow documentation.

• Insert new entry in path_instructions array in .coderabbit.yaml after the SDK users prompt
• Structure with a 5-Priority framework: (1) Accuracy of workflow procedures and tool commands → (2) Coverage of edge cases and gotchas → (3) Alignment with actual codebase conventions → (4) Progressive learning flow (especially for training/ materials) → (5) References to relevant source code and examples
• Include a PHILOSOPHY section: "SDK developers want to CONTRIBUTE to the SDK. Assume mixed expertise—some readers are total beginners, others are experts seeking specific technical details. Documentation should bridge from basic setup to advanced architectural understanding."
• Add CRITICAL PRINCIPLES: verify commands and procedures match actual CI/workflow requirements (DCO signing, GPG, conventional commits, changelog entries), ensure training materials follow logical progression (setup → concepts → workflows), validate references to source code files and examples are accurate
• Add domain-specific guidance: check that contribution workflow steps align with CONTRIBUTING.md, verify Git/GitHub procedures match actual repository setup, ensure references to internal architecture (Executable, transaction lifecycle, retry logic) are technically accurate, validate that training numbering is sequential and logical

🤖 Prompt for AI agents

This phase adds three new path instruction entries to `.coderabbit.yaml` for
documentation review, following existing patterns with priority frameworks,
philosophy sections, and domain-specific guidance.

Add `docs/**` path instruction with:
- 5-Priority framework: (1) Code/commands/links correctness (2) Clarity (3)
Completeness (4) Consistency (5) Accessibility
- PHILOSOPHY: work-in-progress docs, focus on correctness/clarity over
perfection, suggest filing issues for major gaps
- CRITICAL PRINCIPLES: validate URLs, ensure code snippets are syntactically
correct and current, check steps are executable
- AVOID: demanding large-scale restructures, linting-style markdown feedback,
changing conventions without rationale

Add `docs/sdk_users/**` path instruction with:
- 5-Priority framework: (1) Code snippet correctness/completeness (2)
Step-by-step clarity (3) No SDK knowledge assumptions (4) Actionable
instructions (5) Real-world applicability
- PHILOSOPHY: users want to USE SDK quickly/correctly, not learn internals;
concrete, self-contained, immediately actionable
- CRITICAL PRINCIPLES: assume zero SDK knowledge, verify complete examples
(imports, init, error handling), explicit ordered steps, match current API
patterns
- Domain guidance: correct import paths (`from hiero_sdk_python.X import Y`),
transaction patterns match examples/, show error handling

Add `docs/sdk_developers/**` path instruction with:
- 5-Priority framework: (1) Workflow/tool command accuracy (2) Edge
cases/gotchas (3) Codebase convention alignment (4) Progressive learning flow
(5) Source code references
- PHILOSOPHY: developers want to CONTRIBUTE; mixed expertise audience; bridge
basic setup to advanced architecture
- CRITICAL PRINCIPLES: verify CI/workflow commands (DCO, GPG, conventional
commits, changelog), logical training progression, accurate source code
references
- Domain guidance: align with CONTRIBUTING.md, verify Git/GitHub procedures,
validate architecture references (Executable, transaction lifecycle, retry
logic), sequential training numbering

Phase 2: Validate and Polish

Review the added prompts for consistency with existing patterns and effectiveness for the documentation review use case.

Task 1: Verify Structural Consistency

Ensure new documentation prompts follow the same formatting and organizational patterns as existing examples and tests prompts.

• Confirm each prompt uses the established structure: 5-Priority framework with numbered items, PHILOSOPHY section explaining core principle, CRITICAL PRINCIPLES for hard requirements, AVOID section for boundaries
• Verify YAML syntax is correct (proper indentation, use of |- for multi-line strings if needed, correct path glob patterns)
• Check that priority language matches existing prompts' tone (assertive but focused, technical over stylistic)
• Validate that domain-specific guidance references actual SDK patterns (import paths, transaction lifecycle concepts, contribution requirements) rather than generic documentation advice

Task 2: Align with Ticket Requirements

Verify implementation satisfies all ticket acceptance criteria and implementation notes.

• Confirm prompts emphasize PRINCIPLES over rigid rules (particularly in the general docs/** prompt)
• Verify differentiation between SDK users (want to USE quickly/correctly) and SDK developers (want to DEVELOP/contribute) is clear in respective prompts
• Check that prompts acknowledge docs are work-in-progress by suggesting issue filing for major gaps rather than demanding perfection
• Ensure no suggestions for large-scale restructures unless current structure blocks understanding
• Validate that URL/link checking is included where feasible (CRITICAL PRINCIPLES sections)

🤖 Prompt for AI agents

This phase validates the three new documentation prompts for consistency with
existing patterns and alignment with ticket requirements.

Verify structural consistency:
- Confirm all prompts use established structure: 5-Priority framework,
PHILOSOPHY, CRITICAL PRINCIPLES, AVOID sections
- Check YAML syntax: proper indentation, multi-line string formatting (`|-`),
correct path glob patterns
- Validate tone matches existing prompts: assertive but focused, technical over
stylistic
- Ensure domain-specific guidance references actual SDK patterns (import paths,
transaction lifecycle, contribution requirements)

Verify ticket alignment:
- Confirm PRINCIPLES emphasis over rigid rules (especially in `docs/**`)
- Check clear differentiation: SDK users (USE quickly/correctly) vs SDK
developers (DEVELOP/contribute)
- Verify work-in-progress acknowledgment: suggest issue filing for major gaps vs
demanding perfection
- Ensure no large-scale restructure suggestions unless structure blocks
understanding
- Validate URL/link checking in CRITICAL PRINCIPLES sections

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase adds three new path instruction entries to `.coderabbit.yaml` for
documentation review, following existing patterns with priority frameworks,
philosophy sections, and domain-specific guidance.

Add `docs/**` path instruction with:
- 5-Priority framework: (1) Code/commands/links correctness (2) Clarity (3)
Completeness (4) Consistency (5) Accessibility
- PHILOSOPHY: work-in-progress docs, focus on correctness/clarity over
perfection, suggest filing issues for major gaps
- CRITICAL PRINCIPLES: validate URLs, ensure code snippets are syntactically
correct and current, check steps are executable
- AVOID: demanding large-scale restructures, linting-style markdown feedback,
changing conventions without rationale

Add `docs/sdk_users/**` path instruction with:
- 5-Priority framework: (1) Code snippet correctness/completeness (2)
Step-by-step clarity (3) No SDK knowledge assumptions (4) Actionable
instructions (5) Real-world applicability
- PHILOSOPHY: users want to USE SDK quickly/correctly, not learn internals;
concrete, self-contained, immediately actionable
- CRITICAL PRINCIPLES: assume zero SDK knowledge, verify complete examples
(imports, init, error handling), explicit ordered steps, match current API
patterns
- Domain guidance: correct import paths (`from hiero_sdk_python.X import Y`),
transaction patterns match examples/, show error handling

Add `docs/sdk_developers/**` path instruction with:
- 5-Priority framework: (1) Workflow/tool command accuracy (2) Edge
cases/gotchas (3) Codebase convention alignment (4) Progressive learning flow
(5) Source code references
- PHILOSOPHY: developers want to CONTRIBUTE; mixed expertise audience; bridge
basic setup to advanced architecture
- CRITICAL PRINCIPLES: verify CI/workflow commands (DCO, GPG, conventional
commits, changelog), logical training progression, accurate source code
references
- Domain guidance: align with CONTRIBUTING.md, verify Git/GitHub procedures,
validate architecture references (Executable, transaction lifecycle, retry
logic), sequential training numbering
===============================================================================

Task: 2

This phase validates the three new documentation prompts for consistency with
existing patterns and alignment with ticket requirements.

Verify structural consistency:
- Confirm all prompts use established structure: 5-Priority framework,
PHILOSOPHY, CRITICAL PRINCIPLES, AVOID sections
- Check YAML syntax: proper indentation, multi-line string formatting (`|-`),
correct path glob patterns
- Validate tone matches existing prompts: assertive but focused, technical over
stylistic
- Ensure domain-specific guidance references actual SDK patterns (import paths,
transaction lifecycle, contribution requirements)

Verify ticket alignment:
- Confirm PRINCIPLES emphasis over rigid rules (especially in `docs/**`)
- Check clear differentiation: SDK users (USE quickly/correctly) vs SDK
developers (DEVELOP/contribute)
- Verify work-in-progress acknowledgment: suggest issue filing for major gaps vs
demanding perfection
- Ensure no large-scale restructure suggestions unless structure blocks
understanding
- Validate URL/link checking in CRITICAL PRINCIPLES sections

💡 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!

[Mounil2005]

Hey, I'd like to work on this, can you pls assign it to me?