القائمة
PRD editorial standard for docs/. Use when writing a new PRD, extending one, or reviewing changes under docs/ — and when another skill needs the PRD rules.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use whenever adding an e2e compiler-output test (our JS vs the reference compiler) — a new cluster case under `tasks/compiler_tests/`.
🧩 PARITY · Turn one divergence from the Original into a test per affected case (does not fix).
Use when starting any compiler task or session before touching parser/analyze/transform/ast/codegen/css/diagnostics code, before proposing a design or writing code, and when the task grows into a new layer and you need its PRD invariants.
🔪 SDT · verdict-directed review of backend codegen/transform. Use when auditing codegen/transform for smart-analyzer / dumb-codegen violations, or when porting a transform/codegen visitor from the Original.
The required unit-test format for `crates/**/src/**` — use when writing or reviewing a Rust `#[test]`, a test helper, or an `assert_*`. Not for `tasks/compiler_tests/` (use add-test) or `tasks/diagnostic_tests/` (use add-diagnostic-test).
Create a new diagnostic parity test case. Use when the user asks to add a diagnostic test, create a new `tasks/diagnostic_tests/cases/<name>` case, or capture a false positive/false negative against npm `svelte/compiler` before implementation.
| name | writing-docs |
| description | PRD editorial standard for docs/. Use when writing a new PRD, extending one, or reviewing changes under docs/ — and when another skill needs the PRD rules. |
| allowed-tools | Read, Edit, Write, Grep, Bash |
A PRD records a layer's invariants — what stays true across every implementation of that layer. This skill is the standard that keeps a PRD worth reading: durable, load-bearing, one fact in one place. A PRD is not an API reference, not a code map, not a changelog, not a task tracker.
The agent's default is to write down whatever seems useful right now. But a stale or duplicated line is not free storage — it is a distractor that pulls the model off the invariant that matters. Two gates and one home rule replace that default.
Pick your branch:
docs/ changes → Reviewing a diff.A line earns its place only if it passes both gates. If it fails, delete it — don't reword it.
Durable, not status. The line is true independently of the current code. A sentence a merged PR could falsify is status, and status has another home. Fails the gate: line numbers (lib.rs:108), "current state / first vertical slice / WIP / TODO / stub / filled in by later slices / awaiting /audit", percent-done, "not yet implemented", inventories of what already emits vs. what will. Write the target invariant — true in six months ("the template is emitted here, the script in the transform") — not a snapshot of progress ("only static attributes are emitted so far"). Partial coverage of a feature goes in an issue link, never an inline slice list.
Load-bearing. The line changes a decision when writing or reviewing code. Test it: delete the line — does any implementation choice change? No → it's a no-op (a default the agent already honors: "code must be correct", "follow the principles") — cut it. A weak invariant is sharpened into a checkable one, not kept for volume. A checkable invariant carries its mechanical check where one exists: "grep Emit over the crate is empty", "enforced by the Node enum macro". Where none exists, anchor it with one canonical example, not an enumeration of every form — an example is a compressed check read at a glance; the exhaustive list is the wall of text that rots first.
Every fact lives in exactly one document. A copy in two places bloats context and desyncs first.
| Fact | Home |
|---|---|
| Glossary term / ubiquitous-language definition | context.md |
| Where code lives (crate, module, entry point) | map.md (crate/module — no :line, it drifts) |
| A layer's invariant | that layer's PRD, and only there |
| Status / progress / TODO / work plan | GitHub Issues |
| Why a decision was made (rationale) | docs/adr/ or docs/designs/ — the PRD carries the rule, the ADR the reason |
A PRD names a glossary term (bold on first use) but never redefines it. Moving a fact to another home means deleting it from the old one — one copy in two places is a defect, not a backup.
The lines right under a PRD's title:
label: <slug>
topics: <canonical glossary terms, comma-separated>
topics: exists for one consumer: the required skill greps this line to pull the PRD into context by a task's terms, never judging by filename. How it greps is required's to own; how you write the line follows from it:
_Avoid_ synonym. The searcher names terms in glossary vocabulary (required maps synonyms through _Avoid_), so a topic must match that vocabulary. Term not in the glossary yet → add the article to context.md first, then list it here.required greps the stem (derived, each, bind), not the decorated form. Make the stem a literal substring: derived already covers $derived / OptimizedDerived; write each (or EachBlock), never only {#each}.Add a concept to a PRD → add its term here in the same edit. A PRD without topics: is invisible to routing.
Title and frame, then the sections the layer needs — take what applies, not all of them.
# PRD: (root)label: topics:
<1–2 sentences of frame: the crate(s), the place in the pipeline, the layer's principle, the client/server counterpart.>
The single question this layer answers. One paragraph.
Numbered. Each opens with a bold lead and passes The two gates. Mechanical check inline where one exists.
Concrete violations to scan for (*Emit* reads, template knowledge in the transform) — the recognizable bad forms, not a re-wording of the invariants above.
Cross-links with section anchors (context.md §"Principles").
Prose: compiler terminology over anything else; a glossary term bold on first use; no connective filler; the CLAUDE.md identifier ban holds in examples too.
Run The two gates on every added line, and check Single home and The topics contract — most review findings are just these three by name. Two the gates don't cover: the Anatomy prose conventions hold (glossary term bold, from the glossary not an _Avoid_ synonym, no banned identifier); anchors in Cross-document links resolve to sections that exist.