Jrepp - Client Sdk Rfc

.claude/commands/submit-pr.md

@@ -58,64 +58,89 @@ You are tasked with creating or updating a pull request following these strict g
 
 ## PR Body Requirements
 
+**Goal**: Answer WHY, HOW, WHAT in ~10 lines for quick reviewer comprehension.
+
 Use this exact structure:
 
 ```markdown
-## Summary
+## Why
+<1-2 sentences: Problem being solved or value being added>
 
-<2-3 bullet points of technical changes, no fluff>
+## How
+<2-4 bullets: Key implementation approach, no file paths unless critical>
 
-## Changes
+## What Changed
+<2-4 bullets: Specific changes with measurable impact>
 
-### Category 1
-- Specific change with file reference
-- Another specific change
+## Testing
+- [ ] Tests pass (`make test`)
+- [ ] <Optional: Critical test scenario>
+```
 
-### Category 2
-- Change with measurable impact (e.g., "reduces build time by 30%")
+**Body Rules**:
+- **Keep it SHORT**: Target 10-15 lines total, max 20 lines
+- **Why first**: Reviewers need context before diving into code
+- **How = approach**: Architecture/design decisions, not line-by-line changes
+- **What = impact**: Focus on user/system-visible changes, quantify when possible
+- **No file paths**: Reviewers will see files in diff view
+- **No implementation details**: Code review is for that
+- **No checklists beyond Testing**: Keep it simple
+- NO emojis, NO marketing language, NO enthusiasm
+- Use imperative mood in bullets ("Add X", not "Added X")
+
+**Examples**:
 
-## Technical Details
+**Good PR Body** (12 lines):
+```markdown
+## Why
+RFC-040 requires client SDKs for Rust/Python/Go to reduce integration friction.
 
-<Optional: Architecture decisions, trade-offs, implementation notes>
+## How
+- Define pattern-centric APIs (Producer, Consumer, KeyValue)
+- OAuth2 client credentials flow for authentication
+- Testcontainers for integration tests with real backends
+
+## What Changed
+- Add RFC-040 with SDK architecture for 3 languages
+- Define shared directory structure across SDKs
+- Specify 85% test coverage targets and benchmarks
 
 ## Testing
+- [x] Documentation validation passes
+```
 
-- [ ] Unit tests pass
-- [ ] Integration tests pass
-- [ ] Manual testing completed
-- [ ] <Any specific test scenarios>
+**Bad PR Body** (too verbose, 35+ lines):
+```markdown
+## Summary
+This PR adds RFC-040 which is a comprehensive architecture document for client SDKs...
 
-## Breaking Changes
+## Changes
+### Documentation
+- Added docs-cms/rfcs/RFC-040-client-sdk-architecture.md with full specification
+- Updated docusaurus/docs/changelog.md:13-67 with detailed summary
+- Created comprehensive testing strategy section
+...
+```
 
-<List any breaking changes or "None">
+## Writing Guidelines
 
-## Dependencies
+**Clarity Principles**:
+- **Why**: Focus on problem/value, not process ("Reduce integration friction" not "Team asked for SDKs")
+- **How**: Architecture/approach only ("OAuth2 auth flow" not "Add oauth2.rs file")
+- **What**: Impact, not filenames ("Define 3-language SDK spec" not "Update RFC-040-client-sdk.md")
 
-<List any new dependencies or "None">
-```
+**Quantify When Possible**:
+- ✅ "Reduce build time from 5m to 3m"
+- ✅ "Add 15 test cases covering edge cases"
+- ✅ "Specify 85% coverage target"
+- ❌ "Much faster builds"
+- ❌ "Tons of new tests"
 
-**Body Rules**:
-- Use bullet points, not paragraphs
-- Include file paths when relevant (e.g., `.github/workflows/ci.yml:45`)
-- Quantify improvements (time, size, performance)
-- NO emojis (except in checklist items if appropriate)
-- NO marketing language ("amazing", "awesome", "incredible")
-- NO excessive enthusiasm or fluff
-- Focus on WHAT changed and WHY, not how great it is
-
-## Data-Driven Language
-
-**Use**:
-- "Reduces build time from 5m to 3m"
-- "Adds 15 new test cases covering edge cases"
-- "Fixes race condition in consumer pattern"
-- "Implements RFC-042 merge queue specification"
-
-**Avoid**:
-- "Much faster builds!"
-- "Tons of new tests!"
-- "Amazing fix for the pattern!"
-- "Awesome implementation!"
+**Technical, Not Enthusiastic**:
+- ✅ "Fix race condition in consumer pattern"
+- ✅ "Implement RFC-042 merge queue"
+- ❌ "Amazing fix for the pattern!"
+- ❌ "Awesome implementation!"
 
 ## Creating the PR
 
@@ -139,23 +164,22 @@ EOF
 
 Before submitting, verify:
 - [ ] Title is under 72 chars, no emoji, imperative mood
-- [ ] Body has clear structure with bullet points
-- [ ] No marketing language or excessive enthusiasm
-- [ ] Specific file paths or line numbers where relevant
-- [ ] Quantified improvements where possible
-- [ ] Breaking changes and dependencies documented
+- [ ] Body answers Why, How, What in ~10-15 lines
+- [ ] No file paths (reviewers see diffs)
+- [ ] No implementation details (code review is for that)
+- [ ] No marketing language or enthusiasm
+- [ ] Quantified improvements where applicable
 - [ ] Testing checklist included
 - [ ] Branch name follows {username}/feature pattern
-- [ ] All relevant commits are included
 
 ## If PR Exists
 
 When updating an existing PR:
 1. Fetch current PR: `gh pr view <number> --json title,body`
-2. Analyze for quality issues (emoji, fluff, poor structure)
-3. Rewrite according to rules above
+2. Analyze for quality issues (verbose, emoji, missing Why/How/What structure)
+3. Rewrite to Why/How/What format (10-15 lines)
 4. Update with `gh pr edit`
-5. Add comment explaining update: `gh pr comment <number> --body "Updated PR description for clarity and technical accuracy"`
+5. Add comment: `gh pr comment <number> --body "Rewrote description for reviewer clarity"`
 
 ## User Prompt Inclusion
 
@@ -167,9 +191,8 @@ User request: "<original user request>"
 
 ## Output to User
 
-After creating/updating PR:
-1. Show PR URL
-2. Summarize key changes (3-5 bullets)
-3. Note any validation warnings
-4. DO NOT include emoji in your response
-5. Keep response concise and factual
+After creating/updating PR, show:
+1. PR URL
+2. Why/How/What summary (3 bullets max)
+3. Any validation warnings
+4. Keep response under 5 lines

.github/workflows/docs-pr.yml

@@ -0,0 +1,77 @@
+name: Docs PR Validation
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs-cms/**'
+      - 'docusaurus/**'
+      - 'tooling/build_docs.py'
+      - 'tooling/validate_docs.py'
+      - '**/*.md'
+      - '.github/workflows/docs-pr.yml'
+
+# Cancel in-progress runs for the same PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  validate-docs:
+    name: Validate Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docusaurus/package-lock.json
+
+      - name: Install Node dependencies
+        run: cd docusaurus && npm ci
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Validate documentation
+        run: uv run tooling/validate_docs.py
+
+      - name: Build documentation
+        run: uv run tooling/build_docs.py
+
+      - name: Check for broken links in built docs
+        run: |
+          echo "Documentation validation and build completed successfully"
+
+  docs-status:
+    name: Docs Status Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    needs: [validate-docs]
+    if: always()
+
+    steps:
+      - name: Check validation status
+        id: docs_check
+        run: |
+          if [[ "${{ needs.validate-docs.result }}" != "success" ]]; then
+            echo "❌ Documentation validation failed"
+            echo "status=failure" >> $GITHUB_OUTPUT
+            exit 1
+          else
+            echo "✅ Documentation validation passed"
+            echo "status=success" >> $GITHUB_OUTPUT
+          fi