### What?
Migrates the `.claude/commands/pr-status.md` slash command into the
`.agents/skills/pr-status-triage/` skill, restructuring the files so
that `SKILL.md` has a single unified workflow and supporting details
live in the appropriate reference files. Deletes the original command
file.
### Why?
The pr-status automated workflow existed in two places: a basic 6-step
outline in `SKILL.md` and a detailed 10-step procedure in
`.claude/commands/pr-status.md`. This duplication meant the skill was
incomplete without the command file, and the command file couldn't
benefit from the skill's supporting reference files (`workflow.md`,
`local-repro.md`).
### How?
**`SKILL.md`** — Replaced the old 6-step overview with a unified 7-step
workflow covering: background `--wait` script launch, failure/review
analysis, blocker-first prioritization, flaky test checking, local
reproduction, resolving review threads, and retriggering CI when only
flaky tests remain. Step 7 now includes a retry loop: after
retriggering, wait 5 minutes and re-triage from step 1, up to 5 times.
**`workflow.md`** — Extended with content from the command file:
subagent prompt templates (CI failures + review comments), summary table
format examples, failure category taxonomy (8 categories), and review
comment category taxonomy (7 types). Existing sections (prioritization
order, failure handling rules, common patterns, resolving review
threads) preserved.
**`local-repro.md`** — Expanded the "Match CI Environment Variables"
section with feature flag details (`__NEXT_USE_NODE_STREAMS`,
`__NEXT_CACHE_COMPONENTS`), the `NEXT_SKIP_ISOLATE` warning for module
resolution fixes, and a concrete example command.
**`AGENTS.md`** — Updated the stale `/pr-status` command reference to
point to the `$pr-status-triage` skill.
**`.claude/commands/pr-status.md`** — Deleted (all content migrated).
### Files changed
| File | Action |
|------|--------|
| `.agents/skills/pr-status-triage/SKILL.md` | Rewritten with unified
workflow (includes retry loop for flaky CI) |
| `.agents/skills/pr-status-triage/workflow.md` | Extended with
templates, tables, categories |
| `.agents/skills/pr-status-triage/local-repro.md` | Expanded env var
section |
| `AGENTS.md` | Updated skill reference (1 line) |
| `.claude/commands/pr-status.md` | Deleted |
---------
Co-authored-by: Tobias Koppers <[email protected]>
Co-authored-by: Claude <[email protected]>
Writing skills for guides and API reference for more consistent
formatting.
- `write-guide` - this skill helps create guides with progressive
disclosure and a consistent format (intro, summary, step-by-step
instructions, next steps). Works best when you give agents a demo.
- `write-api-reference` - this skill looks at the API type (component,
function, file, etc) and helps draft references following a consistent
format. Works best when you give agents context. e.g. source code, PR
descriptions, RFCs. Also explores repo context (e.g. e2e tests)
Note:
- While skills help you write a first draft, they’re 80%. Humans still
need to check for accuracy, test APIs, and take it to 110%.
- If no technical writing guidance is provided, skills work best when
you give it references of past work.
Closes:
- https://linear.app/vercel/issue/DOC-6245/create-guide-skill
- https://linear.app/vercel/issue/DOC-6246/create-api-reference-skill
---------
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
When snapshotting we create a number of iterators to encode every `shard` of the `modified` dashmap.
Some of these shards end up being empty and rarely they might all be empty. To avoid the overhead of opening a write transaction we detect this prior to persisting. Unfortunately this is done in a single threaded pass and can be expensive since there are often thousands of shards.
To improve this we move the filtering into shard production so it can happen concurrently.
This is a small improvment, from vercel-site builds timing the `Finished writing to filesystem cache` event we get
Before: 6.6s 7.8s 7.1s
After: 6.6s 6.5s 6.4s
So a small progression
## Summary
- Add a `--wait` flag to `scripts/pr-status.js` that writes a partial
report with currently available CI results, then blocks on `gh run
watch` until CI completes, and re-runs the full analysis to produce the
final report
- Refactor `main()` into a reusable `runAnalysis()` function so it can
be called twice (partial + final)
- Update the `/pr-status` command to run the script with `--wait` in the
background, present the partial report immediately while CI is still
running, then poll for completion with 5-minute timeouts
### How it works
1. `/pr-status` launches `node scripts/pr-status.js --wait` in the
background (1-minute Bash timeout)
2. The script writes the initial report (with whatever jobs have
completed so far) and prints `Output written to ...`
3. The command polls for that message using `TaskOutput` with 20-second
timeouts, then reads `index.md` and analyzes the partial results
4. Meanwhile, the script blocks on `gh run watch` until CI finishes,
then re-runs the full analysis
5. After presenting the partial analysis, the command polls for the
background script to complete using `TaskOutput` with 5-minute timeouts
(repeating if needed)
6. When it finishes, the command re-reads the final report and analyzes
any newly failed jobs
### Files changed
- `scripts/pr-status.js` — Extracted `runAnalysis()` from `main()`,
added `--wait` flag with `gh run watch` blocking and re-analysis
- `.claude/commands/pr-status.md` — Updated workflow to use `--wait`
with background execution, poll for readiness (20s timeouts), and poll
for final results (5-min timeouts)
## Test plan
- [ ] Run `node scripts/pr-status.js <completed-pr-number>` (no
`--wait`) — should behave identically to before
- [ ] Run `node scripts/pr-status.js <completed-pr-number> --wait` —
should produce report and exit immediately (no waiting needed since CI
is done)
- [ ] Run `node scripts/pr-status.js --wait` on a branch with
in-progress CI — should write partial report, block on `gh run watch`,
then write final report
- [ ] Run `/pr-status` command — should show partial results, then
update with final results after CI completes
---------
Co-authored-by: Claude <[email protected]>
## Summary
- **Agent skills**: 9 new skill files in `.agents/skills/` covering DCE,
flags, react-vendoring, runtime-debug, PR triage, and skill authoring
- **PR status tooling**: `scripts/pr-status.js` script and
`.claude/commands/pr-status.md` command
- **AGENTS.md**: updated with skill references and development
guidelines
## Test plan
- [ ] No runtime behavior changes
- [ ] Docs and tooling only
---------
Co-authored-by: Tim Neutkens <[email protected]>
Improve performance and token usage of `/ci-failures` command
include type in failure table, provide more instructions
use subagents
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the PR.
- Read the Docs Contribution Guide to ensure your contribution follows the docs guidelines: https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. (A discussion must be opened, see https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added (https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to understand the PR)
- When linking to a Slack thread, you might want to share details of the conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
### What?
Adds a new Claude Code skill `/update-docs` that guides maintainers
through updating Next.js documentation based on code changes.
### Why?
To help ensure PRs include complete and accurate documentation updates
by providing a structured workflow, code-to-docs mappings, and quick
reference materials for Next.js doc conventions.
### How?
The skill includes:
- Main workflow in `SKILL.md` with step-by-step guidance for analyzing
changes, updating docs, and scaffolding new feature documentation
- `references/DOC-CONVENTIONS.md` - Complete frontmatter schema, code
block formatting, and MDX component usage
- `references/CODE-TO-DOCS-MAPPING.md` - Maps source code directories to
their corresponding documentation paths
### Usage
**Manual invocation:**
```
/update-docs
```
**Automatic triggers** - the skill activates when you mention:
- "update documentation for my changes"
- "check docs for this PR"
- "what docs need updating"
- "sync docs with code"
- "scaffold docs for this feature"
- "document this feature"
- "review docs completeness"
- "add docs for this change"
- "what documentation is affected"
- "docs impact"
- References to `docs/`, `docs/01-app`, `docs/02-pages`, or `.mdx files`
adding basic config with graphite/repo instructions
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the PR.
- Read the Docs Contribution Guide to ensure your contribution follows the docs guidelines: https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. (A discussion must be opened, see https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added (https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to understand the PR)
- When linking to a Slack thread, you might want to share details of the conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
