Project Use Cases

Stage 1: Identifying use cases for a feature (Needs use cases)

The primary goal of this stage is to translate a technical web platform feature into a carefully selected set of its most common and important use cases. This is the first of three stages in creating guidance:

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

Identifying action-oriented tasks

A "use case" in this project is not a description of a feature; it's a task that the user is trying to implement, or a problem they're trying to solve. The feature is only relevant in the sense that it's part of the recommended solution for the use case.

• Action-oriented thinking: Frame every use case as a task, and make sure it starts with a verb. Instead of "Scroll-driven animations support horizontal scrolling," use something like "Synchronize an animation's progress with the horizontal scroll distance of a container."
• Bridge the knowledge gap: Assume the developer knows what they want to build (e.g., "I need a sticky header that shrinks on scroll") but might not know which modern web feature is the best solution (e.g., scroll-driven animations). Your use cases should facilitate this discovery by focusing on the desired outcome.
• Balance Generality and Distinctness: The use case description should be general enough to capture the overall intent and match a wide range of user prompts. However, to leverage the vector search effectively, ensure the guide uses clear, descriptive headings. The RAG system chunks content by heading, making specific parts of your guide discoverable for specific prompts. The implementation details within those chunks must remain distinct and specific to ensure the agent receives an unambiguous solution. For example, instead of saying "Fade an image in/out..." in the description, say "Smoothly hide/show a component...".
• Focus on the WHAT not the HOW: Do not mention the solution in the use case description. NEVER mention the specific API methods, properties, or the target feature name in the description itself. For example, avoid phrases like "...by doing..." or "...through the use of...". Ideally, the use case description should remain constant, even if the recommended features or best practices for implementing it change over time.
• Scope: Aim for 2-5 distinct use cases per feature. Each use case should represent a distinct implementation pattern or a significant variation in how the feature is applied. IMPORTANT: Not every sub-feature or feature variation needs a use case.
• MANDATORY: Drop niche use cases: Every guide must solve a tangible, high-priority developer need. Do not document niche features or visual tricks with negligible practical impact. Omit use cases unlikely to match real developer prompts.
• Merge rather than split: If two proposed use cases would result in guides that are 99% identical, combine them into one, more general use case. Duplicate guides bloat context windows and create confusing contradictions.
• Break down complex features: Conversely, do not cram multi-step, intricate features (like passkeys) into a single generic guide. Split them into logical, detailed use cases.
• UX-Driven, Not Feature-Driven: Do not simply list every method, property, or option of an API as a separate use case. A use case must represent a distinct user experience goal or a distinct developer problem, not just a variation in API usage. If the implementation across proposed use cases is 90% identical, consolidate them.
• Avoid Forcing Use Cases on Low-Level Utilities: If a feature is a low-level utility (like a new Promise method or a general object cloning function) that primarily acts as a drop-in replacement for legacy patterns, avoid forcing it into multiple outcome-oriented use cases. Instead, consider recommending a single 'Fundamental Guide' (e.g., "Deep cloning complex objects") or placing it in a top-level discipline skill file.
• Granular Guide Decomposition (Avoid Monoliths): For discipline-level guides, ensure the guidance is broken down into granular "subskills" (i.e., smaller, focused guides) rather than a single monolithic guide. Monolithic guides are too complex to evaluate in the harness, as they present too many best practices to test simultaneously. The primary discipline-level guide (either a category root guide at guides/<category>/<category>/guide.md, such as guides/css/css/guide.md, or a named guide registered in DISCIPLINE_GUIDES in lib/guide-validation.ts, such as guides/wasm/cpp-on-the-web/guide.md) should serve as a conceptual "hub" that establishes the agent's mental model for the discipline, explaining when and how to reference each granular subskill guide, and linking them via the {{ GUIDE_REF("guide-slug") }} macro.

Minimizing overlap

This guidance is ultimately served through a RAG (Retrieval-Augmented Generation) search system. If multiple guides have significant overlap, coding agents may struggle to select the most relevant one, leading to confusing or contradictory advice.

• Check existing guides: Before creating a new use case, review existing guides in the same discipline.
• Search by web-feature-id: Each guide lists the web features it relies on in the web-feature-ids metadata field. Search for the ID of the feature you're writing about in existing guides and open PRs to see how it's being used.
• Merge or differentiate: If your proposed use case is substantially similar to an existing one, do not create a duplicate. Instead, consider how the existing guide should be updated to include your new scenario as a variation or a specific directive.
• Distinct value proposition: Every new guide must offer a distinct solution to a distinct problem.