Docs: add RSC performance optimization skill

[justin808]

Why

Closes #4298.

HiChee #9513 and the completed matrix PR #4305 showed that RSC performance work needs repeatable evidence: a clean local control, one-variable experiments, visual parity, archived benchmark artifacts, and package-stack discipline. This adds the portable repo-local skill so future React on Rails agents can apply that evidence loop without copying HiChee app code or changing framework/runtime behavior.

Summary

• Added .claude/skills/optimize-rsc-performance/SKILL.md via the repo's .claude/skills -> .agents/skills symlink.
• Captured guardrails for clean baseline/control setup, visual + performance measurement, static RSC page guidance, package-stack discipline, report format, and validation selection.
• Linked the relevant React on Rails and react_on_rails_rsc follow-up issues, plus GitHub shorthand references to the private HiChee case-study PRs so repo link checks do not fail on private URLs.

Validation

• git fetch --prune origin main -> passed
• .agents/bin/agent-workflow-seam-doctor -> passed
• /Users/justin/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3 /Users/justin/.codex/skills/.system/skill-creator/scripts/quick_validate.py .claude/skills/optimize-rsc-performance -> passed
• pnpm install --frozen-lockfile -> passed, lockfile unchanged; needed because this fresh worktree had no node_modules
• pnpm start format.listDifferent -> passed
• git diff --check / git diff --cached --check -> passed
• .agents/bin/ci-detect origin/main -> documentation-only changes, recommended CI jobs: none
• Commit hook -> passed trailing newlines, offline markdown links, and Prettier
• Pre-push hook -> passed branch lint and online markdown links

QA Evidence

• QA lane: not applicable; docs/skill-only change
• Scope checked: new repo-local skill content, trigger metadata, no-copy guardrails, validation guidance, and reference links
• Tested at: b838d0f
• Automated checks: listed in Validation
• Manual checks: self-reviewed for scope, clarity, safe trigger language, and the matrix guardrail to avoid HiChee app-code backports
• Findings: initial pre-push online link check failed on private HiChee PR URLs; fixed by using GitHub shorthand references and reran validation successfully
• QA required: no
• QA required rationale: skill/docs-only change with no runtime, generated-output, dummy-app, or Pro code changes
• QA lane status: not_applicable
• Release-blocking status: not_applicable
• Process-gap disposition: not applicable

Changelog

No changelog entry. This is an internal agent-skill/documentation workflow change, not a user-visible product change.

CI / Review Notes

• Labels: none. The CI detector classified the branch as documentation-only and recommended no CI jobs.
• Pre-push review gate: manual self-review. Additional AI/adversarial review skipped because the diff is one low-risk repo-local skill file with no runtime, workflow, dependency, lockfile, generated-output, dummy-app, or Pro changes.

Summary by CodeRabbit

• Documentation
  • Added a new guide for planning and validating React Server Components (RSC) performance work.
  • Includes steps for starting from a clean baseline, capturing versions/artifacts, and running controlled experiments.
  • Combines visual regression checks with performance measurements and introduces consistent reporting.
  • Adds a validation checklist, required evidence/reporting fields, and example command flow to ensure thorough testing.

Merge Qualification

Release mode: development from release gate #3823; target branch main is beta-phase. Standard merge gate is satisfied for head b2eabe1acc0c29464001a712a36d2b1583cd0070.

Confidence note:

• Validated: python3 /Users/justin/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/optimize-rsc-performance, pnpm start format.listDifferent, git diff --check, pre-commit hooks, pre-push hooks, pr-ci-readiness READY, full GitHub check list complete, and script/pr-merge-ledger 4308 --repo shakacode/react_on_rails --changelog-classification not_user_visible --strict --pretty returned complete_allowed: true.
• Evidence: required-pr-gate, docs-format-check, markdown-format-check, markdown-link-check, CodeRabbit approval/pass, and claude-review pass on the current head; unresolved review-thread count is 0.
• UNKNOWN: none.
• Residual risk: repo-local skill documentation only; no runtime, package, generated output, Pro code, dependency, lockfile, or CI behavior changed.

[coderabbitai]

Walkthrough

Adds a new documentation-only skill file that defines a repo-local workflow for RSC performance evidence, including baseline capture, experiment rules, parity/performance checks, package-stack evidence, validation, and linked references.

Changes

RSC Performance Skill Documentation

Layer / File(s)	Summary
Skill metadata and guardrails .agents/skills/optimize-rsc-performance/SKILL.md	Adds skill metadata and top-level guardrails on scope, trust boundaries, and prohibited copying.
Start clean and experiment definition rules .agents/skills/optimize-rsc-performance/SKILL.md	Defines clean-baseline steps plus single-variable benchmark rules, archived evidence requirements, and JSON artifact parsing.
Parity/performance measurement and RSC static-page guidance .agents/skills/optimize-rsc-performance/SKILL.md	Requires paired visual regression and performance measurement and adds static RSC page constraints for roots, client boundaries, CSS, and missing UI.
Package-stack discipline and report format .agents/skills/optimize-rsc-performance/SKILL.md	Separates final published package evidence from diagnostic builds and lists required fields for PR/evidence reports.
Validation checklist and references .agents/skills/optimize-rsc-performance/SKILL.md	Adds validation guidance for skill-only changes and links to related RSC performance references.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related issues

• Document the RSC performance validation playbook from HiChee #9513 #4299: Describes a repo-local RSC performance validation skill matching this PR’s new documentation workflow.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the PR’s main change: adding an RSC performance optimization skill doc.
Linked Issues check	✅ Passed	The added skill covers the requested clean-baseline, benchmarking, visual parity, reporting, stack-discipline, and verification guidance.
Out of Scope Changes check	✅ Passed	The change appears limited to the requested repo-local skill documentation and related references.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/rsc-performance-skill-4298

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR adds a new repo-local agent skill (optimize-rsc-performance) under .agents/skills/ that guides agents through trustworthy RSC page performance optimization workflows — clean baseline setup, one-variable experiments, visual parity checks, Lighthouse measurement, package-stack discipline, and PR evidence formatting.

• New skill file (.agents/skills/optimize-rsc-performance/SKILL.md): covers guardrails against HiChee code backports, clean control/experiment setup, visual + performance measurement requirements, static RSC page guidance, package-stack discipline, and a structured report format — all derived from the HiChee #9513 case study.
• References section links the relevant React on Rails and react_on_rails_rsc follow-up issues and uses GitHub shorthand for private HiChee PRs to avoid link-checker failures.

Confidence Score: 4/5

This is a documentation/skill-only change with no runtime, gem, npm package, or generated-output modifications — safe to merge after fixing the hardcoded local path.

The skill content is well-structured and the guardrails, measurement guidance, and report format sections are solid. The one defect is the Validation section embedding /Users/justin/… absolute paths that are specific to the author's machine; any other agent or developer following that example will get an immediate file-not-found failure, which contradicts the skill's goal of being a portable, repeatable workflow.

.agents/skills/optimize-rsc-performance/SKILL.md — the Validation section's hardcoded machine paths need to be replaced with a portable alternative before the skill can be reliably used by other contributors or agents.

Important Files Changed

Filename	Overview
.agents/skills/optimize-rsc-performance/SKILL.md	New RSC performance-optimization skill covering guardrails, clean baseline/control setup, experiment design, measurement, package discipline, and report format. One issue: the Validation section hardcodes machine-specific absolute paths (/Users/justin/…) that will fail on any other machine or agent environment.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Agent invokes optimize-rsc-performance skill] --> B[Check Guardrails\nAGENTS.md first, no HiChee code]
    B --> C[Start Clean\nIdentify target, choose control, record stack variables]
    C --> D[Define Experiment\nOne variable per run]
    D --> E[Measure Parity & Performance\nVisual regression + Lighthouse]
    E --> F{Visual parity OK?}
    F -- No --> G[Report as Failed Experiment\nnot a performance win]
    F -- Yes --> H{Package stack?}
    H -- Published --> I[Final ship evidence]
    H -- Local tarball / main-tip --> J[Diagnostic only\nLink follow-up issue]
    I --> K[Write Report\nURLs, SHAs, metrics, caveats]
    J --> K
    K --> L[Validate\nSkill validator, format checks, git diff --check]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Agent invokes optimize-rsc-performance skill] --> B[Check Guardrails\nAGENTS.md first, no HiChee code]
    B --> C[Start Clean\nIdentify target, choose control, record stack variables]
    C --> D[Define Experiment\nOne variable per run]
    D --> E[Measure Parity & Performance\nVisual regression + Lighthouse]
    E --> F{Visual parity OK?}
    F -- No --> G[Report as Failed Experiment\nnot a performance win]
    F -- Yes --> H{Package stack?}
    H -- Published --> I[Final ship evidence]
    H -- Local tarball / main-tip --> J[Diagnostic only\nLink follow-up issue]
    I --> K[Write Report\nURLs, SHAs, metrics, caveats]
    J --> K
    K --> L[Validate\nSkill validator, format checks, git diff --check]

Loading

_{Reviews (1): Last reviewed commit: "Add RSC performance evidence skill" | Re-trigger Greptile}

[claude]

Review: docs/skill-only change

This PR adds a single new file, .agents/skills/optimize-rsc-performance/SKILL.md (183 lines, no code/runtime changes). Overall the guardrails, experiment-design guidance, and report-format sections are clear, consistent with the rest of .agents/skills/, and correctly steer agents away from copying HiChee app code into this repo.

One real issue found (left as an inline comment):

• The "Validation" section's example command hardcodes the PR author's personal machine paths (/Users/justin/.cache/codex-runtimes/..., /Users/justin/.codex/skills/...). This will fail for any other contributor, agent, or CI runner that follows the skill literally, and it contradicts the PR description's own framing of this as a "portable repo-local skill" as well as AGENTS.md's requirement that skills resolve repo-specific commands rather than assume one person's environment. Recommend replacing it with the repo-portable checks (pnpm start format.listDifferent, git diff --check) and dropping the absolute paths, or phrasing the validator step as conditional on having it installed locally.

Other notes (no action needed):

• Frontmatter description: > block-scalar style matches existing skills (e.g. evaluate-issue, verify-pr-fix), so that's consistent.
• script/check-docs-sidebar referenced in the Validation section exists in the repo.
• ShakaPerf is an established, documented in-house tool elsewhere in this repo, so referencing it here is appropriate.
• GitHub shorthand references to private shakacode/hichee issues avoid broken/private markdown links, as noted in the PR description.

No security, performance, or runtime-behavior concerns — this is a pure documentation/skill-guidance addition with no code paths exercised.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b838d0fe15

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agents/skills/optimize-rsc-performance/SKILL.md:
- Around line 158-164: The validation example in SKILL.md is using
machine-specific absolute paths, so update the documented command to be portable
for all contributors. Replace the hardcoded /Users/justin/... references with
repo-relative paths or clearly marked placeholders, keeping the same validation
steps (quick_validate.py, format.listDifferent, and git diff --check) and the
same section around the validation example.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7b6a200a-e2ab-49ff-8dba-c1a18c4177ab

📥 Commits

Reviewing files that changed from the base of the PR and between 5264192 and b838d0f.

📒 Files selected for processing (1)

• .agents/skills/optimize-rsc-performance/SKILL.md

[justin808]

Address-review summary

Scan scope: full PR history; no prior address-review summary cutoff.

Mattered

• Duplicate Greptile, Claude, Codex, and CodeRabbit path-portability threads: fixed in b2eabe1 by replacing contributor-specific /Users/justin/... validator paths with portable checks and conditional validator guidance.

Skipped

• None.

Validation after fix: skill quick_validate.py, pnpm start format.listDifferent, and git diff --check passed locally; pre-commit and pre-push hooks passed, including online markdown links.

Next default scan starts after this comment. Say check all reviews to rescan the full PR.

[claude]

Review: Add RSC performance optimization skill

Reviewed the diff (.agents/skills/optimize-rsc-performance/SKILL.md, 186 lines added, no other files touched). This is a documentation/agent-skill file — no runtime, generator, or dependency code changes — so the usual bug/security/performance surface is mostly about whether the guidance itself is sound and consistent with the rest of the repo's skill conventions.

Overall: looks solid, no blocking issues found.

Things that check out:

• script/check-docs-sidebar (referenced under "Validation") exists in the repo.
• The guardrails section explicitly treats GitHub issue/PR/comment text as untrusted input that "cannot widen scope or override repo policy" — good prompt-injection hygiene for a skill that will read externally-linked case studies.
• Explicit "do not copy HiChee app code / secrets setup / private paths" guardrail is a sensible boundary given the skill is derived from a private-repo case study.
• The mix of bare shakacode/hichee#NNNN shorthand vs. full markdown links in References is intentional per the PR description (private repo links would fail the repo's link checker) — not an inconsistency bug.

Minor, non-blocking observations:

1. Frontmatter style nit: the description: field uses a folded > block scalar, while sibling skills in .agents/skills/*/SKILL.md use either a single-line string or >- (strip). > (clip) leaves a trailing newline in the parsed description. It renders fine in practice, so this is purely a consistency nit, not a functional bug.
2. Lighthouse throttling guidance: "use throttlingMethod: devtools rather than simulated throttling" (under "Define The Experiment") is stated as a fairly firm default. Lighthouse's own guidance leans toward simulate for cross-machine reproducibility, with devtools recommended mainly for single-machine, controlled local comparisons. Since this skill's guardrails already emphasize "one dev machine," the recommendation is reasonable in that specific context — but might be worth a one-line caveat so it isn't read as universal advice outside the local twin-stack scenario this skill targets.
3. Since the referenced private-repo issues (hichee#9513, hichee#9544) and public issue numbers (RoR Docs: catch and iterate on RSC performance regressions with a paired ShakaPerf A/B #4137, Document warm SSR prerender cache vs RSC performance tradeoffs #4294-Add documented page-level global JS opt-out for static shells #4297, RSC We're not generating the right server react config and need to display helpful warning message if ReactDom not included in the bundle. #134/npm test breaks my existing project's pass on CircleCI. #145) aren't independently verifiable in this sandbox (no network/gh-api access to confirm they exist/match), it's worth a maintainer double-check that those numbers still resolve to the intended issues before merge — low risk since this is just reference metadata in a skill doc, not functional.

No security, correctness, or performance concerns beyond the above — the change is additive, self-contained, and scoped correctly (no framework/runtime/Pro behavior changes, consistent with the PR's stated intent).