rl-docs-hub

Documentation Policy

Purpose

rl-docs-hub is the canonical documentation repository for RL products and shared platform standards. Teams must treat it as the first place to check before planning, implementation, and review work starts.

Core policy

1. Check the docs hub first
   • Before planning starts
   • Before implementation starts
   • Before opening any PR
2. Document before coding and before PR creation
   • The required documentation must exist or be updated before code work proceeds.
3. Use the hub as the source of truth
   • Do not let critical architecture, API, business-rule, or AWS environment knowledge live only in chat, PR comments, or heads.
4. Record important decisions, not every conversation
   • Capture decisions that materially affect product behavior, architecture, standards, security posture, permissions, or operating model.
   • Do not dump entire chat transcripts into the repo.

Mandatory documentation scope before coding starts

The following must be documented for new work or materially changed work:

• product / feature scope
• product design
• business logic and business rules
• API specifications
• database schema
• technical design
• technical architecture
• data flow diagrams
• IaC / AWS environment architecture diagrams
• associated permissions and access model

If any of the above is intentionally not applicable, that exception must be stated explicitly.

Ownership expectations

• Product and feature intent must be clear enough for engineering to implement without guessing.
• Architecture and design must be clear enough for reviewers to assess fitness and impact.
• Permissions and environment docs must be clear enough for infra/security review.
• App-specific docs live under docs/apps/<repo>/.
• Shared standards and governance live in top-level shared sections.

Change discipline

• Update docs in the same workstream as the change that introduces or modifies the behavior.
• If implementation diverges from docs, the docs must be corrected before the related PR is considered complete.
• When there is conflict between code and docs on intended behavior, resolve the conflict explicitly; do not leave ambiguity in place.