PDaC artifact templates

Copy the file for the kind you need, replace the ID, fill the sections. That is a valid PDaC artifact; no tool is needed to author one. To scaffold a repository at once, download the ten model templates as a zip: it extracts as docs/product/model/, every file already in its place, and the extracted set validates clean. The Product Change is not in the zip on purpose: your first change is CHG-INITIAL, authored for your product, not extracted from an example.

The files come verbatim from the specification repository’s templates directory, where a check validates every one of them against the v1alpha1 schemas and the required sections of the artifacts chapter on every change. What you copy cannot have drifted from the specification. They are non-normative, like the diagrams: where a template and the specification appear to disagree, the specification wins.

They use EXAMPLE IDs and one small worked domain, meeting room booking, and they reference each other, so the set also shows the relationships each type carries. Replace the IDs with your own before the first review; an ID is immutable once accepted. The comment inside each file explains its type and names where the file lives in the reference layout (the file is always named by its lowercase ID); delete the comment as you fill the template in.

Actor

---
id: ACT-EXAMPLE-001
type: actor
title: Member
status: draft
actor-kind: human
---

<!--
Actor: who or what interacts with the product to achieve a meaningful outcome.
Actors are not personas: no demographics, no fictional detail.
actor-kind: human | external-system | scheduled-process | product.
Reference layout: docs/product/model/actors/act-example-001.md (the file is named by its lowercase ID).
Contract: spec/artifacts.md (Actor). Fields: spec/frontmatter-reference.md.
Copy this file, replace the id (immutable once accepted), fill the sections,
and keep them in this order. More sections may follow the required ones.
-->

## Purpose

A member books shared meeting rooms for their team.

## Goals

- Find a free room that fits the meeting.
- Hold the room with confidence that nobody else gets it.

## Responsibilities

- Provides the meeting time, expected attendance and any equipment needs.
- Cancels bookings that are no longer needed.

## Boundaries

A member manages only their own bookings. Approving exceptional requests is outside this actor's reach.

Journey

---
id: JRN-EXAMPLE-001
type: journey
title: Reserve a room for a recurring meeting
status: draft
primary-actor: ACT-EXAMPLE-001
steps:
  - use-case: UC-EXAMPLE-001
---

<!--
Journey: an end-to-end outcome pursued by an actor. It may cross use cases,
channels, bounded contexts, waiting periods, branches and failure paths.
steps: the main ordered path only, one `- use-case:` entry per step; branches
and exceptional paths belong in the body. No screen-by-screen UI behaviour.
Reference layout: docs/product/model/journeys/jrn-example-001.md (the file is named by its lowercase ID).
Contract: spec/artifacts.md (Journey). Fields: spec/frontmatter-reference.md.
-->

## Intended Outcome

The member's team meets in a suitable room every week without rebooking by hand.

## Entry Conditions

The member belongs to an organisation with bookable rooms.

## Journey Narrative

The member finds a room that fits the team, books it for the first occurrence, and repeats the booking for the series. When a conflict appears later in the series, the member resolves it by moving that occurrence.

## Variants and Branches

- No room fits the whole series: the member books the largest available room and splits the remainder.
- A booked room is withdrawn from service: the affected occurrences need rebooking.

## Completion Conditions

Every occurrence of the series holds a confirmed booking.

Use Case

---
id: UC-EXAMPLE-001
type: use-case
title: Book a room
status: draft
primary-actor: ACT-EXAMPLE-001
bounded-context: BC-EXAMPLE-001
governed-by:
  - BR-EXAMPLE-001
uses-terms:
  - TERM-EXAMPLE-001
---

<!--
Use Case: one concrete interaction through which an actor obtains a product
outcome. The body describes observable behaviour, not implementation design.
Optional frontmatter: supporting-actors, bounded-context, governed-by, uses-terms.
Reference layout: docs/product/model/use-cases/uc-example-001.md (the file is named by its lowercase ID).
Contract: spec/artifacts.md (Use Case). Fields: spec/frontmatter-reference.md.
-->

## Goal

The member holds a confirmed booking for a specific room and time.

## Trigger

The member requests a room for a chosen time.

## Preconditions

The member is entitled to book rooms in their organisation.

## Main Flow

1. The member picks a time and sees which rooms are free.
2. The member picks a room and confirms.
3. The booking is recorded and the member receives the confirmation.

## Alternative Flows

- The preferred room is taken: the member picks another free room at the same time.

## Failure Conditions

- The requested start lies beyond the booking lead time (BR-EXAMPLE-001): the booking is rejected with the reason.

## Postconditions

The room is held for the member; the time no longer appears as free to others.

Business Rule

---
id: BR-EXAMPLE-001
type: business-rule
title: Booking lead time
status: draft
applies-to:
  - UC-EXAMPLE-001
uses-terms:
  - TERM-EXAMPLE-001
---

<!--
Business Rule: durable product knowledge that governs behaviour. A rule used by
several use cases or requirements is defined once, here, and referenced by ID,
never restated inside stories, acceptance criteria, code or tests.
The Rule section holds exactly one clear normative statement.
Reference layout: docs/product/model/business-rules/br-example-001.md (the file is named by its lowercase ID).
Contract: spec/artifacts.md (Business Rule). Fields: spec/frontmatter-reference.md.
-->

## Rule

A booking may start no more than 60 days after the day it is made.

## Rationale

Rooms booked far ahead sit idle while plans change; a bounded window keeps availability honest.

## Examples

A booking made on March 1 may start on any day up to April 30.

## Exceptions

None.

Domain Term

---
id: TERM-EXAMPLE-001
type: domain-term
title: Booking
status: draft
defined-in: BC-EXAMPLE-001
synonyms:
  - reservation
---

<!--
Domain Term: shared meaning, defined where it holds. The definition must say
more than the title does. defined-in names the bounded context that owns the
term. Reference layout: docs/product/model/domain/terms/term-example-001.md (the file is named by its lowercase ID).
Contract: spec/artifacts.md (Domain Term). Fields: spec/frontmatter-reference.md.
-->

## Definition

A booking is a member's confirmed hold on one room for one continuous time span.

## Distinguish From

A request that has not been confirmed is not a booking; neither is a room's opening schedule.

## Usage

Use booking for the confirmed hold itself. A cancelled booking stays a booking in history; it does not become a request again.

Bounded Context

---
id: BC-EXAMPLE-001
type: bounded-context
title: Scheduling
status: draft
---

<!--
Bounded Context: a product-language boundary, delimiting where a set of domain
terms carries a specific meaning. It implies nothing about modules or code
structure. Term ownership is derived from each Domain Term's defined-in; do not
author owns-terms here.
Reference layout: docs/product/model/domain/bounded-contexts/bc-example-001.md (the file is named by its lowercase ID).
Contract: spec/artifacts.md (Bounded Context). Fields: spec/frontmatter-reference.md.
-->

## Responsibility

Scheduling answers who holds which room at which time, and keeps overlapping holds impossible.

## Language

Booking, room, time span, lead time. Within Scheduling, availability always means bookable time, not physical readiness.

## Boundaries

Scheduling ends where payment, room maintenance and building access begin.

## External Relationships

Scheduling learns which rooms exist from facility management, and reports usage to it.

Functional Requirement

---
id: FR-EXAMPLE-001
type: functional-requirement
title: Reject bookings beyond the lead time
status: draft
derived-from:
  - BR-EXAMPLE-001
verification:
  - scenario: A booking whose start lies beyond the lead time is rejected and the member is told the earliest permitted start.
    id: BEYOND-LEAD-TIME
uses-terms:
  - TERM-EXAMPLE-001
---

<!--
Functional Requirement: a derived product obligation stating what the product
must do, in explicit normative language, never a disguised implementation task.
derived-from: the use cases, business rules or constraints it follows from.
verification: each entry is either an inline scenario (optional stable id makes
it citable by anchor) or exactly one scenario-ref naming a Structured Behaviour:
  - scenario-ref: SB-EXAMPLE-001
The body should not restate the verification entries.
Reference layout: docs/product/model/requirements/functional/fr-example-001.md (the file is named by its lowercase ID).
Contract: spec/artifacts.md (Functional Requirement). Fields: spec/frontmatter-reference.md.
-->

## Requirement

The product MUST reject any booking whose start lies more than the permitted lead time after the day the booking is made.

## Rationale

Derived from BR-EXAMPLE-001: the lead time only protects availability if the product enforces it at the moment of booking.

Quality Requirement

---
id: QR-EXAMPLE-001
type: quality-requirement
title: Availability answers feel immediate
status: draft
quality-attribute: responsiveness
applies-to:
  - UC-EXAMPLE-001
verification:
  - scenario: Under the agreed reference load, availability for a chosen time is shown within one second for at least 95 percent of requests.
uses-terms:
  - TERM-EXAMPLE-001
---

<!--
Quality Requirement: a measurable quality obligation. quality-attribute names
the quality (responsiveness, portability, determinism, ...). applies-to names
the journeys, use cases or bounded contexts it binds. The Measurement section
must state how conformance is measured; "should be fast" does not qualify.
verification uses the same inline-or-reference union as a Functional Requirement.
Reference layout: docs/product/model/requirements/quality/qr-example-001.md (the file is named by its lowercase ID).
Contract: spec/artifacts.md (Quality Requirement). Fields: spec/frontmatter-reference.md.
-->

## Requirement

Checking a time's availability MUST feel immediate to the member while they compare rooms.

## Measurement

Measured over one week of production traffic: the time from the availability request to the rendered answer, reported as the 95th percentile against the one second bound.

Constraint

---
id: CON-EXAMPLE-001
type: constraint
title: Booking records stay in the customer's region
status: draft
uses-terms:
  - TERM-EXAMPLE-001
---

<!--
Constraint: an externally imposed or deliberately fixed boundary. When
applies-to is absent, the constraint applies to the entire product.
Reference layout: docs/product/model/requirements/constraints/con-example-001.md (the file is named by its lowercase ID).
Contract: spec/artifacts.md (Constraint). Fields: spec/frontmatter-reference.md.
-->

## Constraint

Booking records MUST be stored and processed in the customer's contracted region.

## Rationale

Customer contracts and regional data protection law impose residency; the product does not get to choose.

## Consequences

Availability across regions cannot be answered from one shared store, and moving a customer between regions is a migration, not a setting.

Structured Behaviour

---
id: SB-EXAMPLE-001
type: structured-behaviour
title: Confirm a booking within the lead time
status: draft
illustrates:
  - UC-EXAMPLE-001
  - BR-EXAMPLE-001
given:
  - The room is free for the requested time
  - The requested start lies within the booking lead time
when: The member confirms the booking
then:
  - The booking is recorded for that room and time
  - The member receives the confirmation
uses-terms:
  - TERM-EXAMPLE-001
---

<!--
Structured Behaviour: one concrete, implementation-independent example of
accepted observable behaviour, with its own identity and digest so tests and
specs can cite exactly what they verify. Clause values must not begin with a
GIVEN, WHEN, THEN or AND keyword in any letter case; renderers add those words.
All given entries are conjunctive, all then entries are conjunctive: express an
alternative as a separate Structured Behaviour. Never name test classes, mocks
or other implementation machinery.
Reference layout: docs/product/model/behaviours/sb-example-001.md (the file is named by its lowercase ID). The directory is behaviours, not structured-behaviours.
Contract: spec/artifacts.md (Structured Behaviour). Fields: spec/frontmatter-reference.md.
-->

## Intent

Establish the accepted result of the ordinary booking confirmation, the case every variant is compared against.

## Boundaries

This example does not assert how the confirmation reaches the member, and it does not cover starts beyond the lead time.

Product Change

---
id: CHG-EXAMPLE-001
type: product-change
title: Introduce the booking lead time
status: draft
base-revision: a1b2c3d
operations:
  add:
    - BR-EXAMPLE-001
  modify: []
  remove: []
---

<!--
Product Change: an explicit, validated delta against the accepted definition.
It records semantic intent; a pull request is only its review boundary, and
apply never accepts anything by itself.
base-revision: the commit of the baseline the change was written against
(CHG-INITIAL with no baseline commit uses the 0000000 sentinel).
operations: every added or modified ID needs a complete proposed future-state
artifact under this change's proposed/ directory.
Open Questions is syntactic: a list item counts as unresolved whatever it says;
resolve a question by removing its item. "None." in prose is resolved.
Reference layout: docs/product/changes/active/chg-example-001/change.md.
Contract: spec/product-changes.md. Fields: spec/frontmatter-reference.md.
-->

## Problem

Members book rooms months ahead and abandon them, so free rooms show as taken and trust in availability erodes.

## Intended Product Outcome

A booking may start no more than 60 days after the day it is made, and members are told the earliest permitted start when a request exceeds it.

## Rationale

A bounded window keeps availability honest with the least ceremony; exceptions can come later as their own change if evidence demands them.

## Affected Product Areas

Scheduling (BC-EXAMPLE-001): booking creation (UC-EXAMPLE-001) gains a governing rule.

## Open Questions

None.

## Product Acceptance

The rule reads as intended to the product owner, and the booking use case names it as a failure condition.

## Out of Scope

Enforcement in delivery, migration of existing far-future bookings, and any exception mechanism.