Skip to content

docs: Fold WEB-1142 fleet-wide findings into caching/component skills - #61

Merged
miguelcolmenares merged 1 commit into
mainfrom
docs/web-1142-caching-component-standards
Aug 19, 2026
Merged

docs: Fold WEB-1142 fleet-wide findings into caching/component skills#61
miguelcolmenares merged 1 commit into
mainfrom
docs/web-1142-caching-component-standards

Conversation

@miguelcolmenares

Copy link
Copy Markdown
Member

Summary

A 2026-08 audit across 9 Silver Side Next.js repos (WEB-1142: error handling, plus a follow-up architecture pass) found the same handful of bugs independently, repeatedly, in codebases that never shared code. That's strong evidence these belong in the shipped guidance, not just in one repo's incident log — this PR folds them into the relevant skills, their auto-applied instruction companions, and the review checklist.

Changes Made

  • nextjs-caching skill + caching.instructions.md: the notFound() → HTTP 200 gotcha (an ancestor loading.tsx locks the response status before a notFound() check resolves — reproduced live in 5+ repos), the discriminated-union data-fetching pattern (found/not_found/incomplete/api_error instead of T | null, so a transient upstream error can't get cached as a permanent 404), an explicit status-blindness warning on the CDN/edge-override caching strategy (confirmed caching a live 500 the same as a 200 in one repo), and a new preferred strategy — native ISR via generateStaticParams() { return [] }, which unlocks per-status caching on a dynamic segment with zero pages pre-built at compile time.
  • component-architecture skill + react-components.instructions.md: a "one component per file" rule (found violated independently in 6+ repos — multi-export files like skeleton.tsx/menu.tsx), and the shared <JsonLD> component pattern for structured data instead of inline dangerouslySetInnerHTML script tags (found duplicated in every repo audited, plus a required-data-prop bug found in three forks of one template).
  • domain-driven-design skill: a generic rule — a resolver calling a framework navigation primitive (notFound(), redirect()) belongs colocated with its route, not in lib/.
  • review-code.prompt.md: new caching checklist items and a new Component Architecture checklist section covering all of the above.
  • CHANGELOG.md: [Unreleased] entry summarizing the above.

Numbering in both the caching skill and instructions was preserved deliberately (0. prefix, 2c/2d suffixes) rather than renumbered, per this repo's own documented AGENTS.md warning that markdownlint's MD029 auto-fix previously broke prose in nextjs-caching/SKILL.md that cites items by number.

Type of Change

  • 📝 Documentation

Testing

  • npm run lint, npx tsc --noEmit, npm test (86/86) all pass
  • npm run check (full pipeline: format, lint:md, validate:prompts, typecheck, build, lint, test) passes via the pre-push hook
  • Cross-reference audit: no index/README describing these skills needed updates; no numbered cross-reference broken by the new content

Checklist

  • Code follows project style guidelines
  • Self-review completed (core-review pass, --budget medium)
  • Documentation updated
  • Tests pass locally

A 2026-08 audit across 9 Silver Side Next.js repos (WEB-1142: error
handling + a follow-up architecture pass) found the same handful of
bugs independently, repeatedly, across codebases that never shared
code — strong evidence these belong in the shipped guidance, not just
in one repo's incident log.

nextjs-caching skill + caching.instructions.md:
- notFound() silently returning HTTP 200 when an ancestor loading.tsx
  locks the response status before the check resolves (reproduced live
  in 5+ repos)
- discriminated-union data fetching (found/not_found/incomplete/
  api_error) instead of T | null, so a transient upstream error can't
  get cached as a permanent 404
- the CDN/edge-override caching strategy is inherently status-blind —
  confirmed caching a live 500 the same as a 200 in one repo — now
  explicitly warned against, with generateStaticParams() { return [] }
  documented as the preferred native-ISR alternative

component-architecture skill + react-components.instructions.md:
- one component per file (found violated independently in 6+ repos)
- shared <JsonLD> component instead of inline dangerouslySetInnerHTML
  script tags (found duplicated in every repo audited), including the
  required-data-prop bug found in three forks of one template

domain-driven-design skill:
- a resolver calling a framework navigation primitive (notFound(),
  redirect()) belongs colocated with its route, not in lib/

review-code.prompt.md: checklist items for all of the above.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@miguelcolmenares miguelcolmenares self-assigned this Aug 19, 2026
@miguelcolmenares miguelcolmenares added the enhancement New feature or request label Aug 19, 2026
@miguelcolmenares
miguelcolmenares merged commit d220396 into main Aug 19, 2026
8 of 9 checks passed
@miguelcolmenares
miguelcolmenares deleted the docs/web-1142-caching-component-standards branch August 20, 2026 03:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants