writing-comments

# Writing Comments ## Purpose Comments in this repository are read by contributors, months or years after they were written, with none of the context you have right now. This skill defines who that reader is, what each kind of comment is for, and which patterns are banned. ## Scope Boundary This skill governs **contributor-facing** comments in the TypeScript/JavaScript source. It does **not** apply to end-user documentation: - JSDoc blocks tagged `@docs` in [`packages/astro/src/types/public/config.ts`](../../../packages/astro/src/types/public/config.ts) and [`packages/astro/src/core/errors/errors-data.ts`](../../../packages/astro/src/core/errors/errors-data.ts) are scraped by an external `docgen` tool and published to the Astro docs website. Follow [`packages/astro/src/core/errors/README.md`](../../../packages/astro/src/core/errors/README.md) for those, and get docs-team review — CI regenerates the reference when `types/public/**` changes. - Other JSDoc across `types/public/**` is surfaced to users through editor IntelliSense. Write it for Astro **users** building a site, not for contributors reading the source. Everything below is about the source a contributor reads at HEAD. ## The Reader Write for an Astro contributor who is competent in TypeScript but has **no access to your current context**: not this conversation, not the pull request, not the issue, not the diff. They see only the repository at HEAD. Two consequences follow directly: 1. **...