Date Boundary Calculation Prompt Template

This prompt is designed for reporting pipeline engineers and billing system developers who need to compute date boundaries from an input timestamp. Use it when you need to derive start-of-month, end-of-quarter, start-of-year, or other calendar boundaries programmatically through an LLM call. The prompt produces a boundary timestamp with the boundary type, timezone context, and a flag for DST-affected boundaries. It belongs in workflows where downstream systems require precise temporal partitioning but the boundary calculation logic is embedded in an AI pipeline rather than a deterministic date library.

The ideal user is operating an AI-native pipeline where the model must reason about temporal context as part of a larger natural language or agent workflow. For example, an agent that reads a user's request to 'pull the Q3 reports' must resolve that to explicit start and end timestamps before querying a database. In this scenario, the boundary calculation is one step in a chain that also involves intent classification and tool selection. The prompt expects a reference timestamp in ISO 8601 format, a boundary type specifier (e.g., start_of_month, end_of_quarter), and an IANA timezone string. The output is a structured object containing the computed boundary timestamp, the boundary type, the timezone used, and a boolean dst_ambiguous flag that is set to true when the boundary falls within a DST transition window.

Do not use this prompt when you can compute boundaries with native datetime functions in your application code. If your pipeline is a simple ETL job written in Python, using dateutil or the standard library's datetime module will be faster, cheaper, and provably correct. Reserve this prompt for AI-native pipelines where the boundary calculation is a reasoning step that cannot be easily extracted into a deterministic function, such as when the boundary type itself is inferred from natural language or when the calculation is part of a multi-step agent task that requires the model to maintain state. Even in those cases, implement a post-generation validation layer that verifies the output against a deterministic calculation before the timestamp enters a billing or reporting system.

This prompt template is designed to compute a specific date boundary—such as start-of-month, end-of-quarter, or start-of-year—from a given input timestamp. It is built for reporting pipeline engineers and billing system developers who need deterministic, timezone-aware boundary calculations that can be validated programmatically. The template uses square-bracket placeholders for all dynamic inputs, constraints, and output specifications, making it straightforward to parameterize in your application code before sending it to the model.

textCopy
You are a precise date boundary calculator. Your task is to compute a specific temporal boundary from an input timestamp.

INPUT:
- Timestamp: [INPUT_TIMESTAMP]
- Timezone: [TIMEZONE]

BOUNDARY TYPE TO CALCULATE: [BOUNDARY_TYPE]

CONSTRAINTS:
- [CONSTRAINT_1]
- [CONSTRAINT_2]
- [CONSTRAINT_3]

OUTPUT SCHEMA:
{
  "boundary_timestamp": "ISO 8601 string with timezone offset",
  "boundary_type": "string matching the requested boundary type",
  "timezone": "IANA timezone string used for calculation",
  "dst_affected": boolean,
  "calculation_notes": "string explaining any edge case handling"
}

RULES:
1. Always calculate boundaries in the specified timezone, not UTC, unless explicitly instructed otherwise.
2. For DST transition days, use the actual wall-clock time in the specified timezone. Set dst_affected to true if the boundary falls on a day where a DST transition occurs in that timezone.
3. For month boundaries, handle months with 28, 29, 30, and 31 days correctly based on the year.
4. For quarter boundaries, Q1 ends March 31, Q2 ends June 30, Q3 ends September 30, Q4 ends December 31.
5. For year boundaries, start-of-year is January 1 00:00:00 and end-of-year is December 31 23:59:59.999 in the specified timezone.
6. If the input timestamp is already at the requested boundary, return that same timestamp as the boundary.
7. If the boundary type is ambiguous or unsupported, return an error in the calculation_notes field and set boundary_timestamp to null.

EXAMPLES:
[EXAMPLES]

Now calculate the [BOUNDARY_TYPE] boundary for the provided timestamp.

To adapt this template for your system, replace each square-bracket placeholder with concrete values before sending the prompt to the model. For [BOUNDARY_TYPE], use precise values like start_of_month, end_of_quarter, start_of_year, or end_of_month. The [CONSTRAINT] placeholders let you inject business-specific rules such as fiscal calendar offsets, holiday exclusions, or custom boundary definitions. The [EXAMPLES] placeholder should contain one or two few-shot demonstrations showing the correct calculation for known edge cases—this significantly improves model accuracy at month, quarter, and year transitions. After receiving the model response, validate the output JSON against the schema, verify that the boundary timestamp is logically consistent with the input, and log any cases where dst_affected is true for downstream review. For billing or compliance workflows, always route outputs through a deterministic validation function before ingestion, and flag any boundary calculation where calculation_notes indicates edge-case handling for human approval.

The Date Boundary Calculation prompt is designed to be called as a deterministic function within a larger data pipeline, not as a conversational interface. Wire it as a single-turn completion with strict JSON output constraints. The prompt expects an input timestamp, a boundary type (e.g., start_of_month, end_of_quarter), and a timezone context. It returns a boundary timestamp, the boundary type, the timezone used, and a dst_affected flag. This output should be treated as a structured record that feeds directly into downstream aggregations, billing windows, or report generation queries.

Validation and Retry Logic: Before the output reaches any database or API, validate the JSON schema. Confirm that the returned boundary timestamp is a valid ISO 8601 string, that the boundary_type matches one of the allowed enum values, and that the timezone field is a recognized IANA timezone string. If validation fails, retry once with the same prompt and a prepended error message: The previous output failed validation: [ERROR_DETAILS]. Please correct the output. If the second attempt also fails, log the raw input and failed output, then escalate to a dead-letter queue for manual review. Do not silently fall back to a default boundary—incorrect date boundaries in billing or reporting systems create compounding errors.

Model Choice and Temperature: Use a model with strong instruction-following and JSON mode support, such as gpt-4o or claude-3.5-sonnet. Set temperature=0 to eliminate variance in boundary calculations. Date math is deterministic; any randomness in the output indicates a model failure, not creative interpretation. If your pipeline processes high volumes, consider caching results for identical (timestamp, boundary_type, timezone) tuples to reduce API costs and latency.

DST and Edge-Case Handling: The dst_affected flag is critical for systems that must account for ambiguous or non-existent hours during daylight saving transitions. When this flag is true, downstream systems should treat the boundary timestamp as potentially ambiguous and apply business rules—such as always using UTC internally or flagging the record for human review. Test the prompt explicitly with timestamps near DST transitions (e.g., 2025-03-09T02:30:00 America/New_York for spring-forward gaps and 2025-11-02T01:30:00 America/New_York for fall-back overlaps). Also test month-end boundaries for months with 28, 29, 30, and 31 days, and quarter-end boundaries that cross year boundaries (e.g., end_of_quarter for 2024-12-15 should return 2024-12-31T23:59:59).

Observability and Logging: Log every prompt invocation with the input parameters, the model's raw response, the validated output, and the latency. Attach a prompt_version tag to each log entry so you can correlate boundary calculation changes with prompt template updates. If your pipeline uses a feature store or configuration service, inject the prompt template version at runtime rather than hardcoding it. This makes it possible to roll back a prompt change without redeploying the entire pipeline.

When Not to Use This Prompt: This prompt is not a replacement for a date library. If your application can compute boundaries deterministically using pytz, dateutil, or database-level date functions, prefer those. Use this prompt only when the input timestamp format is inconsistent, the boundary rules are expressed in natural language policy documents that change frequently, or the system must produce human-readable boundary rationales alongside the computed timestamp. For high-throughput, latency-sensitive pipelines, precompute boundary lookup tables and avoid model calls entirely.