Fusion Package Scribe

Package Scribe

Experimental caveat

This skill is experimental and not yet stable. Behavior, structure, and outputs may change between versions.

When to use

Use when you need to systematically add or improve documentation across TypeScript packages — whether a full monorepo sweep or a single package.

Typical triggers:

• "document all packages"
• "improve docs for packages/utils/observable"
• "add TSDoc to all public exports in this package"
• "rewrite the README for this package"
• "run a documentation pass on the monorepo"
• "review the TSDoc quality in this package"

Implicit triggers:

• A package has public exports with missing or stub TSDoc
• A package README is outdated, inconsistent, or missing standard sections
• A documentation sweep is planned across multiple packages

When not to use

• Modifying runtime code (only doc comments and README files)
• Generating API reference sites or TypeDoc output
• Non-TypeScript languages (initial scope is TS/TSX only)
• Auto-merging PRs or bypassing review workflows
• Security vulnerability scanning or performance profiling
• Replacing existing CI-based doc generation pipelines

Required inputs

If required inputs are missing or ambiguous, ask before proceeding.

• Scope: monorepo root path or specific package path(s)
• Mode: single (one package) or sweep (multiple packages)

Conditional inputs

• Package filter: glob or list when processing a subset of packages
• README template path: repo-specific template if not using the built-in default (for example under .github/instructions/)
• Tracking issue: issue number for lifecycle updates (assign, status, close)
• Commit style: repo-specific conventional commit format (defaults to docs(<package>): )
• Batch size: number of packages per batch for sweep mode (defaults to 5)

Defaults

• Mode: single (if only one package path provided)
• Commit prefix: docs(<package-name>):
• Batch size: 5 packages per sweep batch
• README structure: built-in template from references/readme-template.md
• Review council: enabled (runs after every package)

Precedence and standards discovery

This skill discovers and follows the target repository's own standards:

1. Repository instructions — applicable files under .github/instructions/, CONTRIBUTING.md, contribute/ 2. Tooling configuration — tsconfig.json, biome.json, .editorconfig 3. Companion skill — fusion-code-conventions for TSDoc rules, naming conventions, and intent quality (when installed) 4. Built-in defaults — references/tsdoc-checklist.md and references/readme-template.md

Repository-level standards always win. When no repo standards exist, the built-in defaults apply.

Agent modes

In single-agent runtimes, all three roles run inline sequentially.

Instructions

Step 1 — Discover repository standards

Before generating any documentation:

1. Search for repo-level documentation instructions:

• applicable files under .github/instructions/
• CONTRIBUTING.md, contribute/

2. Read tsconfig.json to understand module structure, path aliases, and strict mode settings 3. Read biome.json or equivalent linter config for style expectations 4. Check if fusion-code-conventions is available — if so, defer to its TSDoc rules from references/typescript.conventions.md 5. If no repo-level standards exist, use references/tsdoc-checklist.md as the quality baseline

Step 2 — Discover packages

1. For single mode: validate the provided package path exists and has TypeScript source files 2. For sweep mode:

• Read the root package.json or workspace config (pnpm-workspace.yaml, lerna.json, turbo.json) to find all packages
• Filter by any provided glob/list
• Sort packages by estimated size (file count) for batch planning
• Write the discovery summary to .tmp/scribe-discovery-<context>.md

Step 3 — Plan execution (sweep mode only)

Activate agents/orchestrator.agent.md (or run inline):

1. Group packages into batches of the configured batch size 2. Order batches: smaller packages (fewer source files) first to maximize early throughput 3. Estimate token budget per package: ~100 tokens per source file for reading, ~200 tokens per export for TSDoc generation 4. If a single package exceeds 60% of the estimated context window, flag it for special handling (barrel exports first, defer internal modules) 5. Write the execution plan to .tmp/scribe-plan-<context>.md

Step 4 — Process each package

Activate agents/documenter.agent.md (or run inline) for each package:

4a — Scan public API surface

1. Find the barrel export file (index.ts, index.tsx, or main field in package.json) 2. Trace all re-exports to identify the full public API surface 3. Categorize exports: functions, classes, types/interfaces, constants, hooks, enums 4. Prioritize: barrel exports first, then direct public exports, then internally-consumed-but-exported items

4b — Generate or improve TSDoc

For each public export:

1. Read the existing implementation to understand intent, parameters, return values, error paths, and side effects 2. Check for existing TSDoc — improve rather than replace when present 3. Apply the TSDoc checklist (repo standards or references/tsdoc-checklist.md):

• Summary line: explain why and what problem it solves, not just what it does
• @param for every parameter with meaningful descriptions
• @returns for every non-void function
• @template for every generic type parameter
• @throws for meaningful error paths
• @example for user-facing and non-trivial public APIs
• @deprecated with replacement guidance when applicable

4. Flag and rewrite "name-echo" patterns (for example /** Gets the value. */ getValue()) 5. Do not modify runtime code — only doc comments

4c — Rewrite or improve README

1. Read the existing README (if any) to preserve valuable content 2. Apply the README structure from repo instructions or references/readme-template.md:

• Package name and description
• Features / key exports
• Installation
• Usage with code examples
• API reference (summary of key exports with links or inline docs)
• Configuration (if applicable)

3. Ensure the README is useful to a developer discovering the package for the first time 4. Optimize for retrieval: use clear headings, keyword-rich descriptions, and concrete examples

Step 5 — Review council

Activate agents/reviewer.agent.md (or run inline) after each package:

1. Intent extraction — Does the TSDoc accurately describe what the code does and why? Flag any comment that merely restates the function/type name. 2. Code comprehension — Are complex algorithms, state machines, or side effects explained? Would a new developer understand the code from the docs alone? 3. User-facing quality — Is the README useful to someone discovering the package for the first time? Does it have working examples? 4. Retrieval fitness — Will the documentation produce good hits in RAG / semantic search? Are key terms present in headings and summaries?

The reviewer produces a pass/fail per criterion. Failures loop back to Step 4 for the specific package.

Step 6 — Commit

After the review council passes for a package:

1. Stage only documentation files (.ts/.tsx files for TSDoc changes, README.md) 2. Commit using the repo's conventional commit format, defaulting to:

   docs(<package-name>): improve TSDoc and README documentation

3. Do not push — leave that to the user or a PR workflow

Step 7 — Report

After all packages are processed:

1. Write a summary to .tmp/scribe-report-<context>.md:

• Packages processed and status (pass/fail/skipped)
• Total exports documented
• Review council pass rates per criterion
• Any packages flagged for manual review
• Commits created

2. If a tracking issue was provided, update it with the summary

Expected output

• TSDoc comments on all public exports in processed packages
• Consistent README for each processed package
• One commit per package with documentation-only changes
• Summary report in .tmp/
• Tracking issue update (when issue number provided)

Safety & constraints

This skill is mutation-capable. Repository-local workflow instructions take precedence over inline guidance when they conflict.

• Only modify doc comments and README files — never touch runtime code
• Do not push commits; leave push decisions to the user
• Do not auto-merge PRs or bypass review workflows
• Do not invent API behavior — document only what the code actually does
• Do not delete or replace existing valuable documentation without preserving its content
• When a tracking issue is referenced, update it only after explicit confirmation
• Respect .gitignore and do not commit temporary files from .tmp/
• If the review council fails a package twice, flag it for manual review instead of looping indefinitely

Documenter Agent

Role

Per-package documentation writer. Scans public API surfaces, generates or improves TSDoc on all exports, and rewrites the package README.

When to activate

Activate for every package being processed — both single and sweep mode.

Required context

Before starting, the orchestrator (or main skill) must provide:

• Package path
• Discovered repository standards (from Step 1)
• TSDoc checklist to apply (repo-specific or built-in)
• README template to follow (repo-specific or built-in)

Instructions

Scan public API surface

1. Locate the barrel export:

• Check package.json main, module, exports fields
• Fall back to src/index.ts, index.ts, src/index.tsx

2. Trace all export and export * from statements recursively 3. Build an export inventory:

   Export name | Kind (function/class/type/interface/enum/const/hook) | File | Has TSDoc?

4. Prioritize processing order: 1. Barrel-level re-exports (highest visibility) 2. Directly exported public functions and hooks 3. Exported types and interfaces 4. Exported constants and enums 5. Exported classes

Generate TSDoc

For each export missing or having inadequate TSDoc:

1. Read the implementation — understand what the code does, why it exists, what constraints it operates under 2. Check existing docs — if TSDoc exists, improve it; do not discard valuable existing content 3. Write the summary line — explain the purpose and why it exists, not just restate the name 4. Add required tags per the checklist:

• @param — describe what the parameter controls, not its type
• @returns — describe what the caller receives and any invariants
• @template — explain what the generic represents in domain terms
• @throws — document meaningful error paths with error types
• @example — provide a realistic usage example for user-facing APIs
• @deprecated — include the replacement path

5. Verify against anti-patterns:

• Name-echo: /** Gets the value. */ getValue() → rewrite
• Type-echo: @param id - string → describe purpose instead
• Empty summary with only tags → add meaningful summary
• Missing context on complex logic → add explanatory comments

Write README

1. Read existing README content and preserve valuable information 2. Apply the template structure in order:

   # <Package Name>

   <One-paragraph description of what the package does and why it exists>

   ## Features

   - Key capability 1
   - Key capability 2

   ## Installation

   <Package manager install command>

   ## Usage

   <Primary usage example with code block>

   ## API Reference

   ### <Export Name>
   <Brief description and signature>

   ## Configuration

   <Configuration options if applicable>

3. Write descriptions that are retrieval-friendly:

• Use domain keywords in headings and first sentences
• Include concrete code examples that show real usage
• Avoid vague statements like "provides utilities for..."

4. Cross-reference the export inventory — every key public export should appear in the API Reference section

Quality self-check

Before handing off to the review council, verify:

• [ ] Every public export has TSDoc with at least a summary and @param/@returns where applicable
• [ ] No name-echo or type-echo patterns remain
• [ ] README has all required sections from the template
• [ ] Code examples in README actually reference real exports from the package
• [ ] No runtime code was modified — only doc comments and README

Expected output

• Modified source files with TSDoc comments (doc comments only — no runtime changes)
• Updated or new README.md for the package
• Export inventory summary for the review council

Safety

• Never modify runtime code — only doc comments and README files
• Do not invent API behavior — document only what the code actually does
• Do not fabricate examples using APIs that do not exist in the package
• Preserve existing valuable documentation; improve, do not discard
• Flag any export whose behavior is unclear rather than guessing

Orchestrator Agent

Role

Batch coordinator for sweep-mode documentation passes across multiple packages in a monorepo.

When to activate

Activate in sweep mode when multiple packages need processing. Skip in single-package mode.

Instructions

Plan batches

1. Receive the package list from discovery (Step 2) 2. Sort packages by source file count (ascending — smaller packages first) 3. Group into batches of the configured batch size (default: 5) 4. For each package, estimate token cost:

• Input: ~100 tokens per source file (reading implementation)
• Output: ~200 tokens per public export (generating TSDoc)
• README: ~500 tokens per package (reading + rewriting)

5. Flag any package where estimated cost exceeds 60% of available context window

Handle oversized packages

When a package is flagged as oversized:

• Process barrel exports and direct re-exports first
• Defer internal modules to a second pass
• Split the package into sub-batches if necessary (by directory)
• Document the split in the execution plan

Track progress

Maintain a running status for each package:

• pending — not yet started
• in-progress — documenter is working on it
• review — documenter done, awaiting review council
• passed — review council approved
• failed — review council rejected, needs rework
• skipped — excluded by filter or flagged for manual review

Context isolation

Each package must be processed with a clean context:

• Do not carry TSDoc patterns from one package to another (each package has its own API semantics)
• Do carry repository-level standards (discovered once in Step 1)
• Do carry the execution plan and progress tracker

Batch completion

After each batch:

• Report completed/failed/skipped counts
• Estimate remaining work
• Adjust batch size if packages are consistently larger or smaller than estimated

Expected output

• Execution plan in .tmp/scribe-plan-<context>.md
• Progress updates after each batch
• Final summary statistics for the report (Step 7)

Safety

• Do not skip the review council step to save time
• Do not process packages in parallel beyond what the runtime supports
• If a batch fails entirely, stop and report rather than continuing blindly

Reviewer Agent — Review Council

Role

Quality gate that verifies documentation changes before they are committed. Evaluates TSDoc and README output against four criteria and produces a pass/fail verdict per criterion.

When to activate

Activate after the documenter finishes each package. The review council runs on every package — it is not optional.

Review criteria

1. Intent extraction

Does the TSDoc accurately describe what the code does and why?

Pass when:

• Summary lines explain purpose and motivation, not just the operation name
• @param descriptions explain what the parameter controls in domain terms
• @returns describes what the caller receives and any invariants
• Complex decision logic has explanatory comments

Fail when:

• TSDoc restates the function name: /** Gets the user. */ getUser()
• @param restates the type: @param id - string
• Summary is empty or generic: /** Utility function. */
• Non-obvious business logic has no explanatory comment

2. Code comprehension

Are complex algorithms, state machines, or side effects explained?

Pass when:

• Complex control flow has comments explaining why each branch exists
• State transitions are documented
• Side effects (network calls, mutations, event emissions) are called out
• The documentation alone would let a developer understand and reconstruct the logic

Fail when:

• A function with 3+ branches has no explanatory comments
• A state machine or reducer has no state transition documentation
• Side effects are present but undocumented
• A developer reading only the docs would misunderstand the API contract

3. User-facing quality

Is the README useful to a developer discovering the package for the first time?

Pass when:

• The package description clearly states what it does and why
• Installation instructions are present and correct
• At least one realistic usage example exists with a working code block
• Key exports are listed with brief descriptions
• A new developer could start using the package from the README alone

Fail when:

• The README is just a title and one sentence
• No code examples are provided
• Examples reference APIs that do not exist in the package
• The description is vague ("provides utilities for various things")
• Installation or import paths are wrong

4. Retrieval fitness

Will the documentation produce good hits in RAG / semantic search?

Pass when:

• Headings use domain keywords (not generic "Overview", "Usage" alone)
• First sentences of sections contain the most important terms
• Function summaries use the problem-domain vocabulary, not just code terms
• Examples show realistic scenarios with descriptive variable names

Fail when:

• Headings are generic with no domain context
• Descriptions use only abstract/technical terms without domain grounding
• Key functionality is buried in prose without keyword-rich summaries
• The README would not surface for natural-language queries about the package's domain

Instructions

1. Read the documenter's output: modified source files and README 2. Read the export inventory to ensure completeness 3. Evaluate each criterion independently 4. For each criterion, produce:

• Verdict: pass or fail
• Evidence: specific examples from the output that support the verdict
• Fixes (on fail): concrete corrections the documenter should apply

5. If all four criteria pass → approve the package for commit 6. If any criterion fails → return findings to the documenter for rework 7. If a package fails review twice → flag for manual review and move on

Expected output

## Review: <package-name>

| Criterion | Verdict | Notes |
|---|---|---|
| Intent extraction | pass/fail | ... |
| Code comprehension | pass/fail | ... |
| User-facing quality | pass/fail | ... |
| Retrieval fitness | pass/fail | ... |

### Findings (if any)
- [fail criterion]: specific issue → suggested fix

Safety

• Do not approve documentation that fabricates API behavior
• Do not waive criteria to speed up processing
• Flag uncertainty rather than guessing at pass/fail
• After two failed reviews for the same package, escalate to manual review

Follow-up Questions

Ask only the relevant unanswered questions from this bank. Do not ask all questions — pick the ones that would most reduce ambiguity for the current request.

Scope questions

• Is this a single-package pass or a sweep across all packages?
• Should I process all packages in the workspace, or is there a specific subset?
• Are there packages I should skip (e.g., internal tooling, deprecated packages)?

Standards questions

• Does this repository have documentation standards I should follow? (e.g., files under .github/instructions/, CONTRIBUTING.md)
• Is there a preferred README structure or template?
• Are there TSDoc conventions beyond the standard tags? (e.g., custom tags, specific example formats)

Workflow questions

• Should I commit each package separately, or batch commits?
• What commit message format does this repository use? (e.g., docs(package): description)
• Is there a tracking issue I should update with progress?
• Should I create a PR after committing, or leave that to you?

Quality questions

• How thorough should the @example coverage be? (every export vs. user-facing APIs only)
• Should I preserve existing README content or start fresh?
• Are there specific packages you'd like me to prioritize?

Monorepo questions

• What workspace tool is this monorepo using? (npm workspaces, pnpm, turborepo, lerna, nx)
• Are there shared types packages that other packages depend on? (process those first)
• Is there a package dependency graph I should follow for ordering?

Package Discovery

How to find packages, barrel exports, and public API surfaces in TypeScript monorepos.

Finding packages

Workspace config detection

Check these files in order to discover the package list:

1. pnpm: pnpm-workspace.yaml → packages: array of globs 2. npm/yarn: root package.json → workspaces array of globs 3. turborepo: turbo.json (uses workspace config from package.json or pnpm) 4. lerna: lerna.json → packages array of globs 5. nx: nx.json + workspace.json or project-level project.json

Fallback discovery

If no workspace config exists:

• Scan for directories containing package.json with a name field
• Exclude: node_modules, .git, dist, build, coverage, .tmp

Package metadata

For each discovered package, collect:

• name from package.json
• main, module, exports entry points
• private flag (skip private packages unless explicitly included)
• Source file count (.ts, .tsx in src/ or root)

Finding barrel exports

The barrel export is the primary entry point that defines the public API surface.

Detection order

1. package.json → exports["."] (modern ESM packages) 2. package.json → module field 3. package.json → main field 4. src/index.ts or src/index.tsx 5. index.ts or index.tsx at package root

Tracing re-exports

From the barrel file, recursively follow:

• export { ... } from './module'
• export * from './module'
• export type { ... } from './module'
• export default ...

Build the complete export tree, noting which source file defines each export.

Classifying exports

Prioritization

Process exports in this order for maximum impact: 1. Barrel re-exports — highest visibility, most likely discovered by users 2. Hooks — typically the primary API for React packages 3. Functions — core utilities and business logic 4. Types/Interfaces — API contracts 5. Classes — less common in modern TS but still important 6. Constants/Enums — configuration values and discriminators

Changelog

0.0.2 - 2026-05-07

patch

• #170 `5e43223` - Apply caveman-compress prose style to SKILL.md and references.

• Drop articles, filler, hedging from SKILL.md activation body
• Compress batch-strategy, readme-template, tsdoc-checklist references

0.0.1 - 2026-04-22

patch

• #141 `e84644f` - Add new experimental skill for systematic TSDoc and README documentation across TypeScript monorepo packages

• Orchestrator-based workflow: discover packages, generate TSDoc, rewrite READMEs, review, commit
• Three agent modes: orchestrator (batch planning), documenter (per-package writing), reviewer (review council)
• Repo-aware standards discovery with built-in defaults fallback
• Review council validates intent extraction, code comprehension, user-facing quality, and retrieval fitness
• Token budget guidance and batch strategy for large monorepo sweeps

resolves equinor/fusion-core-tasks#702

Batch Strategy

Orchestrating documentation passes across multiple packages: token budget estimation, batch sizing, context isolation, and failure handling.

Token budget estimation

Estimate token cost per package:

Package cost formula:

cost ≈ (source_files × 100) + (existing_doc_files × 50) + (exports × 200) + 500 + 300

Batch sizing

Default batch size: 5 packages

Adjust based on:

• Smaller packages (< 10 source files): increase batch size to 8-10
• Larger packages (> 50 source files): decrease batch size to 2-3
• Mixed sizes: group similarly-sized packages together

Ordering strategy

Process batches in this order: 1. Smallest packages first — build momentum, catch tooling issues early 2. Related packages together — packages that share types or re-export from each other benefit from being processed in sequence 3. Largest packages last — these may need special handling

Context isolation

Each package: clean working context.

Carry across packages (shared context)

• Repository-level standards (discovered once in Step 1)
• Execution plan and progress tracker
• Commit format and branch conventions

Do NOT carry across packages (isolated per package)

• TSDoc patterns and examples — each package has its own API semantics
• README content and structure decisions
• Export inventories and implementation details
• Review council findings

Why isolation matters

• Prevents "pattern bleed" where TSDoc from a utility package leaks into a domain package
• Each package's documentation should stand alone
• Reduces risk of hallucinated cross-references between unrelated packages

Oversized package handling

When single package exceeds 60% of estimated context window:

1. Split by API surface priority:

• Pass 1: Barrel exports and direct re-exports
• Pass 2: Internally-consumed-but-exported items
• Pass 3: README generation (after all TSDoc is done)

2. Split by directory (for very large packages):

• Process each source directory as a sub-batch
• Generate the README after all directories are processed

3. Flag for manual review if the package cannot be split cleanly

Failure handling

Progress tracking

Maintain a status file at .tmp/scribe-progress-<context>.md:

## Progress

| Package | Status | Exports | TSDoc | README | Review |
|---|---|---|---|---|---|
| @scope/pkg-a | ✅ passed | 12 | 12/12 | ✅ | 4/4 |
| @scope/pkg-b | 🔄 review | 8 | 8/8 | ✅ | 2/4 |
| @scope/pkg-c | ⏳ pending | — | — | — | — |

README Template

Default package README structure when no repository template exists. Adapt depth to complexity — small utility packages may omit Configuration; large packages may split API Reference into sub-sections.

Template

````markdown

<Package Name>

<One-paragraph description: what the package does, what problem it solves, and who it is for. Lead with the outcome, not the implementation.>

Features

• <Key capability 1 — what it enables>
• <Key capability 2>
• <Key capability 3>

Installation

npm install <package-name>
# or
pnpm add <package-name>

Usage

<Primary usage scenario with a realistic, copy-pasteable code example.>

import { mainExport } from '<package-name>';

// Describe the scenario
const result = mainExport(/* realistic args */);

<If the package has multiple primary use cases, show 2-3 focused examples under sub-headings.>

API Reference

<exportName>

<Brief description of what it does and when to use it.>

function exportName(param: Type): ReturnType;

Returns: What the caller receives.

<Repeat for each key public export. For packages with many exports, group by category (hooks, utilities, types, constants).>

Configuration

<Configuration options, environment variables, or setup requirements. Omit this section if the package has no configuration.>

````

Writing guidelines

Description paragraph

• Lead with the outcome the package enables, not implementation details
• Include the problem domain — what area does this package belong to?
• Mention the target audience if not obvious
• Use keywords that would appear in a natural-language search query

<!-- ❌ Implementation-focused -->
# fusion-observable
Provides RxJS-based observable utilities and subscription management.

<!-- ✅ Outcome-focused -->
# fusion-observable
Subscribe to real-time data changes across Fusion modules with automatic cleanup and error recovery. Designed for Fusion app developers who need reactive data flows without manual subscription management.

Features list

• State what each feature enables, not what it is
• Use active verbs: "Tracks...", "Validates...", "Streams..."
• Keep to 3-7 bullets — if more, group under sub-headings

Code examples

• Use realistic variable names and scenarios from the package's domain
• Show the import statement so the reader knows the entry point
• Keep examples minimal but complete — copy-pasteable without additional setup
• Add brief inline comments explaining the why, not the what

API Reference section

• List exports in the same order as the barrel export
• For large packages (15+ exports), group by category with sub-headings
• Include the function signature, parameter table, and return description
• Link to TSDoc in source when the README summary is a subset of the full docs

Retrieval optimization

README should surface for natural-language queries about the package's domain:

• Use domain keywords in headings (not just "Overview" or "API")
• Front-load important terms in the first sentence of each section
• Include the package's common aliases or related terms in the description
• Pair technical terms with plain-language explanations

TSDoc Checklist

Default TSDoc quality rules when no repository-level standards exist. Repository standards (e.g. fusion-code-conventions) take precedence.

Required tags by export kind

Summary line rules

Most important part of TSDoc comment:

1. Purpose — why does this exist? What problem does it solve? 2. Be specific — "Formats a time range for booking calendars" > "Formats time" 3. No name-echo — never restate the export name 4. Lead with outcome — what does caller get or what effect occurs?

Examples

// ❌ Name-echo
/** Creates a user. */
export function createUser(...)

// ✅ Purpose-driven
/** Provisions a new user account with default permissions and sends the welcome email. */
export function createUser(...)

// ❌ Vague
/** A hook for subscriptions. */
export function useSubscription(...)

// ✅ Specific
/** Subscribes to real-time updates for a specific resource and re-renders when data changes. */
export function useSubscription(...)

@param rules

• Describe what the parameter controls or represents in domain terms
• Do not restate the TypeScript type
• Include valid ranges, defaults, or constraints when relevant
• Use @param name - syntax (JSDoc-style dash separator)

// ❌ Type-echo
/** @param id - string */

// ✅ Domain description
/** @param id - Unique identifier of the booking to cancel. Must be a valid UUID. */

@returns rules

• Describe what the caller receives and any invariants
• For promises, describe the resolved value
• For hooks, describe the full return shape (tuple members or object properties)

// ❌ Vague
/** @returns The result. */

// ✅ Specific
/** @returns The cancelled booking with updated status, or null if the booking was already cancelled. */

@template rules

• Explain what the generic represents in domain terms, not just "the type parameter"

// ❌ Generic
/** @template T - The type. */

// ✅ Domain-grounded
/** @template TResponse - Shape of the API response payload after deserialization. */

@throws rules

• Document error paths callers should handle
• Include the error type when known
• Skip for impossible or framework-internal errors

/** @throws {RangeError} When endDate is before startDate. */
/** @throws {AuthenticationError} When the session token has expired. */

@example rules

• Required for all user-facing and non-trivial APIs
• Use realistic variable names and scenarios
• Show the import if usage context is not obvious
• Minimal but complete — copy-paste and run

/**
 * @example
 * ```ts
 * import { formatTimeRange } from '@equinor/fusion-dates';
 *
 * const display = formatTimeRange('2026-03-17T09:00:00Z', '2026-03-17T10:30:00Z');
 * // => "09:00 – 10:30"
 * ```
 */

Anti-patterns to flag