Project Guides

Stage 2: Authoring guidance for a use case (Needs guidance)

This is the second of three stages in creating guidance:

1. Stage 1: Identifying use cases for a feature
2. Stage 2: Authoring guidance for a use case (you are here)
3. Stage 3: Evaluating guidance for a use case

What a real-world coding agent sees

When a developer asks an AI coding assistant to implement something, the assistant retrieves the relevant guide.md via a RAG (vector search) system. guide.md is the only project file a real-world coding agent ever sees. Everything else in a use case directory is eval infrastructure:

Implication for authoring (guide.md & expectations.md): Authors and SMEs strictly author guide.md and expectations.md. You do not hand-author solution.patch, zero-passrate.patch, grader.ts, or task.md. Once guide.md and expectations.md are authored, running gd dev <guide> automatically loops across SUPPORTED_BASE_APPS (daily-grind and devtools-times) inside safe temporary /tmp/ sandboxes to generate and calibrate the evaluation capsules under targets/<base_app>/, runs agent evaluations, and produces an evaluation diagnostic report (test-app-results/report.md). Running gd pr <guide> then automatically commits, pushes, detects PR labels (gd-dev-content or gd-dev-eval), and opens the Pull Request.

Implication for guide.md: Because guide.md is the agent's only source of truth, it must be entirely self-contained. Do not rely on agents reading expectations.md, any target patch, or any external link to understand how to implement the use case.

MANDATORY RULES FOR WRITING guide.md:

1. YAML Frontmatter Schema

guide.md must start with this YAML frontmatter structure (added in Stage 1):

---
name: slugified-use-case-name
description: <do thing> <with feature> (e.g., "Create dynamic color systems using modern color syntax")
web-feature-ids:
  - webstatus-feature-id
---

• web-features: Must be a list of accurate IDs found via webstatus.dev. Include ALL features referenced in the guide body, not just the primary one. If an ID is missing, inform the USER.
  • Pending Features (tmp- prefix): If a feature ID is pending upstream in @web-platform-dx/web-features (e.g. an open issue), use tmp-<candidate-slug> (e.g. tmp-scroll-axis-lock) in guide.md AND register it in features/pending-web-features.json along with its upstream issue link. Optionally add group (a web-features group ID like scrolling, or an array of them) so ATL triage routes it to that group's owner in guides/atls.json (then run node --experimental-strip-types guides/generate-feature-to-groups.ts), and compat_features (a @mdn/browser-compat-data key or array of keys, e.g. ["css.properties.scroll-axis-lock"]) so CI can detect when the feature graduates upstream even if web-features chooses a different final ID than <candidate-slug>. On the GitHub new-feature issue itself, annotate the predicted final ID without the tmp- prefix (<candidate-slug>); the sync and triage scripts automatically strip tmp- when matching guides to issues. When the feature ID is officially released upstream in web-features, validator checks will automatically fail in CI to prompt updating the frontmatter to the official ID.
• draft (optional): Set draft: true (or any truthy value, e.g. draft: future) to withhold the guide from all distribution (search index, README, skills distribution) without deleting it. Set draft: stub when a stub includes author notes in the markdown body so it is still inventoried and validated as a stub. Omit for normal publishing.

2. Tone and Formatting

• Formatting Directives: Use strict imperative directives (MANDATORY:, DO, DO NOT) only when emphasis is strictly needed (e.g., for critical constraints, security, or common pitfalls). Do not overuse them for every single instruction. Coding agents respond best to rigid constraints when they are selectively applied.
• Focus: Keep the guidance focused on the specific use case and short. No fluff. No conversational text. Include a brief overview of the use case and explanation of why the solution outlined in the guide is the recommended approach.
• Self-Contained: DO NOT include any external links in the markdown body ([link text](url)), and DO NOT rely on internal {{ GUIDE_REF("...") }} cross-references to supply required implementation details. All required knowledge to use the feature MUST be fully synthesized into the markdown body (or transcluded at build time via INCLUDE/FEATURE). Agents must not be slowed down or require additional retrievals to implement the guidance.
• American English: Always author guidance in American English (behavior, color, synchronize, center, optimize, etc.) for consistency across documentation, RAG tokens, and search embeddings.

3. Code Snippets

• Include short, heavily commented code snippets.
• Put directives directly in code comments so they are impossible to miss (e.g., <!-- Always use the required attribute -->).
• Code comments MUST explain why a value or approach is chosen, not just what the code does. An agent that copies magic values without understanding them will apply them incorrectly. If a value is context-dependent (e.g., a threshold that should vary by use case), say so explicitly.
• Modern Standards: Exclusively use ES modules (import/export) in JavaScript code examples; avoid CommonJS (require).
• Clarifying Arbitrary Values: Explicitly identify placeholder values (like 2rem or 50ms) as example-only in comments to avoid them being mistaken for strict technical constraints.

4. Implementation Steps

• The implementation steps should assume any web feature can be used. Choose the best feature for the job, regardless of browser support.
• DO NOT suggest modern features just because they are modern. If a modern feature has no distinct user-visible advantage over a legacy feature for the given use case — but will require a more complex fallback implementation — use the legacy feature.
• DO NOT include cross-browser fallbacks in the implementation section. Those should only be mentioned in the fallback section.
• Only mark steps as MANDATORY if they are truly required for the feature to function. Optional steps (e.g., adding scroll snap, adding an event listener for progressive enhancement) must be labeled as optional. Incorrect use of MANDATORY causes agents to implement unnecessary complexity.
• The guide is the agent's only source of truth. DO NOT reference demo.html or any other file — agents won't have access to them. Everything the agent needs to implement the use case must be in guide.md.
• When listing alternatives, say how to choose between them (which use cases favor which). Optional improvements are alternatives too: the choice is between adding them or not, so say when they're worth adding. Don't invent criteria; if the choice genuinely depends on context you can't anticipate, leave it to the agent.

5. Fallback Strategies

If the primary implementation uses features that are not Baseline Widely Available, you MUST include a fallback recommendation in this section.

• Framing: Frame fallback necessity in terms of Baseline target (e.g., "If your Baseline target does not support X, use...").
• Assessment: Start with a broad assessment of the fallback's robustness. Recommend the modern approach if the fallback is robust; highlight complexity/caveats and suggest alternatives (like userland solutions) if it is not.
• Experience: MANDATORY: Explicitly describe the fallback experience (progressive enhancement vs. feature detection/graceful degradation).
• Feature Detection: Checks should be tightly scoped to the interface rather than the instance (e.g. use Object.hasOwn(HTMLElement.prototype, 'onbeforematch') over 'onbeforematch' in window)
• Fallback Options (in order of preference):
  1. Custom Code: Short, reliable reimplementation (<50 lines) using widely available features.
  2. Polyfill: A robust, performant polyfill (see guidelines below).
  3. Abstraction: A well-tested userland library.
  4. Graceful Degradation: Baseline Newly Available features that degrade gracefully.
  5. Progressive Enhancement: Frame as progressive enhancement only if no robust fallback exists.
• Faithfulness: Fallbacks MUST be faithful to the use case. If the primary recommendation gracefully degrades but ultimately doesn't accomplish the core use case, suggest a different fallback if one is available. Graceful degradation IS acceptable for features that enhance, but are otherwise not core to the use case.