proofread-against-docs

name	proofread-against-docs
description	Proofread an existing question/answer/note in this workspace (or a draft about to be captured) against the current Claude Code documentation. Catches claims that have gone stale because the harness changed, surfaces concrete numbers (caps, budgets, env vars) that should be cited, and flags where a fresh source needs logging. Use when revisiting prior notes, before publishing a consolidated export, or as the final step when capturing a new Q&A.
when_to_use	Trigger phrases: "proofread this note", "is this still accurate", "check against the docs", "ground this in the current docs", "fact-check the plugin/context/skill answer". Also run automatically as the last step inside the new-question capture workflow before marking status: answered.
allowed-tools	WebFetch Read Grep Glob Edit Write Bash

Proofread a workspace note against current Claude Code docs

The Claude Code harness changes fast. Notes captured in this workspace are time-stamped for that reason, but a note dated three weeks ago may already describe behaviour that no longer matches the current product. This skill is the routine fix: re-read a target note, pull the relevant doc pages live, and reconcile.

Inputs

You will be given (or should infer):

• A target file — usually under answers/, notes/, or a draft in flight. If the user says "proofread the plugin context note" without a path, search answers/ and notes/ for the most plausible match and confirm before proceeding.
• Optionally, a focus area ("just check the truncation claims", "just check the agent loading bit"). If unspecified, do the whole document.

Procedure

1. Read the target

Read the full target file, including frontmatter. Note:

• The answered / revised date — anything older than ~30 days is a candidate for staleness.
• The sources: list — these are the files this note already cites.
• Any inline numbers, env-var names, frontmatter field names, char limits, file paths, or behavioural claims. These are the testable assertions.

Build a short list of checkable claims. A claim is checkable if it names something concrete (a cap, a budget, an env var, a frontmatter key, a file path, a tool name, a behavioural statement like "X loads eagerly"). Vague claims ("plugins can be expensive") are not in scope.

2. Identify the canonical doc URLs

The workspace's canonical source is https://code.claude.com/docs/en/<page>. Map each checkable claim to the page that would settle it. Common pages:

• https://code.claude.com/docs/en/plugins — plugin structure, manifest, components
• https://code.claude.com/docs/en/plugins-reference — full plugin schema
• https://code.claude.com/docs/en/skills — skill frontmatter, description loading, budget
• https://code.claude.com/docs/en/sub-agents — agent definitions, preloaded skills
• https://code.claude.com/docs/en/hooks — hook events, lifecycle
• https://code.claude.com/docs/en/memory — CLAUDE.md, memory loading
• https://code.claude.com/docs/en/mcp — MCP server config
• https://code.claude.com/docs/en/settings — settings.json keys, env vars
• https://code.claude.com/docs/en/permissions — permission rules, managed settings
• https://code.claude.com/docs/en/how-claude-code-works — context window, compaction
• https://code.claude.com/docs/en/commands — built-in commands and bundled skills

If you're unsure which page covers something, fetch https://code.claude.com/docs/llms.txt first to discover available pages.

3. Fetch each relevant page

Use WebFetch with a focused prompt that names the specific claim being checked. Don't fetch a page and ask for a generic summary — ask the page to confirm or refute the specific assertion. Example:

"Does this page say skill descriptions are truncated to ~80 characters? Quote the actual character limit if any is given. Quote any statements about how/when descriptions are loaded into context."

Fetch in parallel when you have multiple independent claims to check.

4. Reconcile

For each claim, classify the result:

• Confirmed — the docs back it up. Note the URL and a short quote in your reconciliation report so the source can be logged.
• Stale — the claim was true at the original date but the docs now say something different. This is the most important category. Capture the current statement verbatim and the URL.
• Unverifiable — the docs don't address it. Either it's an observation from running the harness (fine, but mark confidence: low if it isn't already) or it should be tested empirically.
• Speculative / inferred — the original note says so. Leave alone unless the docs now confirm or refute.

5. Apply fixes

Default to editing the target file in place rather than appending corrigenda. The repo's convention is that notes should reflect the current understanding; revision history lives in git. Update:

• Inline claims that are now stale.
• Numbers, env vars, frontmatter keys, file paths.
• The frontmatter: bump or add a revised: YYYY-MM-DD field. Add the new source file(s) to sources:. If the note's confidence was high but a key claim turned out to be wrong, lower it.

Preserve the user's voice and the structure of the note. Don't rewrite for style.

6. Log the sources

For every doc page that contributed to the proofread (whether it confirmed or refuted), create or update a file under sources/:

• Filename: sources/YYMMDD-docs-<page-slug>.md using today's date.
• Frontmatter: fetched: YYYY-MM-DD, url: <full URL>, type: official-doc, title: <descriptive>.
• Body: short summary of what this page authoritatively establishes, with direct quotes of the load-bearing sentences. Future proofreads will compare against these snapshots.

If a source for the same page already exists from a recent date (within a week or so), update it in place and bump fetched: rather than creating a duplicate.

7. Report

Output a short reconciliation summary to the user with:

• Target file proofread.
• Each claim checked, classified Confirmed / Stale / Unverifiable.
• For each Stale claim: what changed and what was edited.
• Which source files were created or updated.

Keep this terse — the diff is the substantive output.

When proofreading a draft (not yet captured)

Same procedure, but step 5 is "incorporate the doc-grounded numbers into the draft before it's saved." Do this before status: answered is set on the question file. The point is that nothing leaves the workspace ungrounded.

Anti-patterns

• Don't fetch a doc and paste a generic summary. Ask each fetch a specific question tied to a specific claim.
• Don't trust your training data over the live doc. That's the whole reason for this workflow. If memory and the doc disagree, the doc wins and the note gets edited.
• Don't add corrigenda blocks. Edit in place. Git tracks the change.
• Don't widen scope. If the user asked to check the plugin loading section, don't rewrite the prose elsewhere because you don't like it.
• Don't skip source-logging for a "small" check. The next proofread will compare against this snapshot. A missing source means re-fetching from scratch.