Phase Template
Reusable template for every implementation phase. Copy to docs/<area>-phase-<id>.md or docs/phases/<Area>/ and fill all sections.
Registry-oriented short form also exists at templates/phase-template.md. Prefer this template for AI-driven implementation phases.
Enterprise default: Every phase must run Enterprise Phase Discovery before Implementation, satisfy definition-of-done.md, and deliver applicable mandatory-phase-artifacts.md. CRUD is never sufficient. Derive missing production components inside this phase without pulling future-phase features (boundary-rules.md).
Phase: <Title>
| Field |
Value |
| Identifier |
(e.g. loyalty-7.1) |
| Status |
Planned / In Progress / Complete |
| Owner |
Platform / TBD |
| Module(s) |
|
| Service(s) |
|
| Depends On |
|
| ADR(s) |
|
| Manifest |
phase-manifest.yaml |
| Framework |
ADR-013 · ADR-018 · ADR-019 |
Objective
One paragraph: measurable outcome of this phase.
Enterprise Phase Discovery
Required before Implementation. Copy the full Discovery Record from enterprise-phase-discovery.md.
| Field |
Value |
| Discovery date |
|
| Inputs reviewed |
Roadmap · Architecture · Boundaries · Prior handover · Code · APIs · Domain · Events · Permissions · Aggregates · Tests · Docs |
Baseline Inventory (exists today)
Target Responsibility (this phase when Complete)
Gap Analysis
| Capability |
Status |
Action |
| Business Capabilities |
|
|
| Entities / Value Objects / Aggregates |
|
|
| Services / Policies / Specifications |
|
|
| Repositories / Commands / Queries |
|
|
| REST / Capability / Permission / Health / Metrics APIs |
|
|
| Events / Jobs / Config / Feature Flags / Providers |
|
|
| Validation / Audit / Search / Filter / Sort / Pagination |
|
|
| Soft Delete / Optimistic Locking / Tenant Isolation |
|
|
| Documentation / Tests / Ops / DX |
|
|
Promoted to Implementation Scope
Explicitly Excluded (future phase or other service)
Boundary Confirmations
Business Analysis
| Item |
Detail |
| Actors |
|
| Business capabilities (in phase) |
|
| Success metrics |
|
| Non-goals |
|
Scope
In Scope
Modules
| Module |
Change type |
Notes |
|
new / extend |
|
Domain Model
| Aggregate |
Entities |
Invariants |
|
|
|
Models / Entities
| Entity |
Soft delete |
Audit |
Tenant |
Optimistic lock |
Notes |
|
Yes/No |
Yes/No |
Yes |
Yes/No |
|
Standards: entity-template.md.
DTOs
| Schema |
Create |
Update |
Read |
List |
|
|
|
|
|
Standards: api-template.md.
Repositories
| Repository |
Aggregates |
Tenant filter |
Page/Filter/Sort/Search |
|
|
Required |
|
Standards: repository-template.md.
Specifications
Policies
Commands
Queries
Services
| Service class |
Responsibilities |
|
|
Standards: service-layer-template.md.
Validators
Permissions
| Permission |
Description |
{service}.{resource}.{action} |
|
Events
Standards: event-template.md.
APIs
| Method |
Path |
Permission |
Notes |
| GET |
/health |
public/ops |
|
| GET |
/capabilities |
as designed |
|
| GET |
/metrics |
as designed |
or N/A |
|
/api/v1/... |
|
include page/filter/sort/search on lists |
Standards: api-template.md. OpenAPI must be updated.
Providers
| Interface |
Owning service |
Notes |
|
|
or N/A |
Configuration / Feature Flags / Jobs / Seeds
| Kind |
Items |
Required? |
| Configuration |
|
Yes for runtime |
| Feature flags |
|
If gated |
| Background jobs |
|
If async/scheduled |
| Seed data |
|
If bootstrap/reference needed |
Tests
Mandatory categories (mark N/A with reason only if truly not applicable):
Standards: testing-template.md.
Documentation
Standards: documentation-template.md.
Mandatory Artifacts Trace
Confirm each applicable row from mandatory-phase-artifacts.md is In Scope, Done, or N/A (justified):
Out of Scope
Explicit exclusions (prevent scope creep and future-phase pull-forward):
Completion Criteria
Architecture Impact
Database Impact
Risks
Related Documents
5c6a2e78cf