docs: Fold WEB-1142 fleet-wide findings into caching/component skills - #61
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-cachingskill +caching.instructions.md: thenotFound()→ HTTP 200 gotcha (an ancestorloading.tsxlocks the response status before anotFound()check resolves — reproduced live in 5+ repos), the discriminated-union data-fetching pattern (found/not_found/incomplete/api_errorinstead ofT | 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 viagenerateStaticParams() { return [] }, which unlocks per-status caching on a dynamic segment with zero pages pre-built at compile time.component-architectureskill +react-components.instructions.md: a "one component per file" rule (found violated independently in 6+ repos — multi-export files likeskeleton.tsx/menu.tsx), and the shared<JsonLD>component pattern for structured data instead of inlinedangerouslySetInnerHTMLscript tags (found duplicated in every repo audited, plus a required-data-prop bug found in three forks of one template).domain-driven-designskill: a generic rule — a resolver calling a framework navigation primitive (notFound(),redirect()) belongs colocated with its route, not inlib/.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/2dsuffixes) rather than renumbered, per this repo's own documentedAGENTS.mdwarning that markdownlint'sMD029auto-fix previously broke prose innextjs-caching/SKILL.mdthat cites items by number.Type of Change
Testing
npm run lint,npx tsc --noEmit,npm test(86/86) all passnpm run check(full pipeline: format, lint:md, validate:prompts, typecheck, build, lint, test) passes via the pre-push hookChecklist
--budget medium)