---
name: new-method-implementation
description: >
  Implement or extend a gmt API in packages/gmt/src by reusing existing gmt
  helpers first, then Temporal only when needed, while preserving string-first
  I/O, plain/zoned separation, and fallback-return rules.
metadata:
  library_version: 1.14.1
---

# New Method Implementation

Use this skill when adding a new method under `packages/gmt/src`.

## Required behavior

1. Use existing gmt methods first.
2. If no existing gmt method covers the need, use Temporal to implement a new custom method.
3. Keep public I/O string-first unless the established module pattern is different.
4. Enforce strict input/output shapes: prefer ISO 8601 strings, IANA timezone identifiers, and explicit Unix epoch numbers for inputs. Do not accept fuzzy or ambiguous formats — require callers to canonicalize input or use parse/validate helpers.
5. Keep plain and zoned logic separate.
6. Do not use `Date`, `Date.now`, or manual date parsing.

## Naming conventions

Follow existing patterns for method names:

- ForDate/ForDateTime/ForZoned suffixes for type-specific variants (e.g., `getQuarterForDate`, `getQuarterForZoned`)
- startOf* / endOf* for boundaries (e.g., `startOfQuarterForDate`)
- isBetween* for range checks (e.g., `isBetweenDate`, `isBetweenZoned`)
- get* for getters (e.g., `getQuarterForDate`)

## Implementation flow

1. Discover existing method
- Search `packages/gmt/src/plain` and `packages/gmt/src/zoned` for an existing helper.
- If one exists, use it and do not add duplicate API surface.

2. Decide module boundary
- Put timezone-free logic in `plain/*`.
- Put timezone-aware logic in `zoned/*`.

3. Build with Temporal
- Parse using Temporal constructors.
- Perform immutable Temporal operations.
- Return normalized output in the module's expected shape.

4. Apply fallback policy
- String return type: return `""` on invalid input.
- Number return type: return `null` on invalid input.
- Boolean return type: return `false` on invalid input.

5. Add tests
- Add strong unit tests for valid, invalid, and boundary scenarios.
- Include DST and timezone boundaries for zoned methods.
- Use `it.each` template tables for matrixed test cases.

6. Update exports and docs
- Add to relevant `index.ts` file in the module.
- Add to package.json exports if new subpath needed.
- Update README.md API Surface section.

## Prompter guidance when method does not exist

If requested behavior is not currently covered by gmt:

1. Tell the prompter it is possible via Temporal because gmt ships Temporal.
2. State this requires a new custom gmt method.
3. Ask them to open a GitHub issue requesting the functionality.
4. If they proceed locally, implement the method plus solid unit tests.
5. Recommend they open a PR or include exact proposal details in the issue.