TorbatYar/docs/ai-framework/phase-template.md

# 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](../templates/phase-template.md). Prefer **this** template for AI-driven implementation phases.

**Enterprise default:** Every phase must run [Enterprise Phase Discovery](enterprise-phase-discovery.md) before Implementation, satisfy [definition-of-done.md](definition-of-done.md), and deliver applicable [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md). CRUD is never sufficient. Derive missing production components inside this phase without pulling future-phase features ([boundary-rules.md](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](phase-manifest.yaml) |
| Framework | [ADR-013](../architecture/adr/ADR-013.md) · [ADR-018](../architecture/adr/ADR-018.md) · [ADR-019](../architecture/adr/ADR-019.md) |

## Objective

One paragraph: measurable outcome of this phase.

## Enterprise Phase Discovery

> **Required before Implementation.** Copy the full Discovery Record from [enterprise-phase-discovery.md](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

- [ ] No future-phase pull-forward
- [ ] No service-boundary violation
- [ ] No duplication of another service’s logic
- [ ] CRUD-only delivery rejected

## 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](entity-template.md).

### DTOs

| Schema | Create | Update | Read | List |
| --- | --- | --- | --- | --- |
| | | | | |

Standards: [api-template.md](api-template.md).

### Repositories

| Repository | Aggregates | Tenant filter | Page/Filter/Sort/Search |
| --- | --- | --- | --- |
| | | Required | |

Standards: [repository-template.md](repository-template.md).

### Specifications

| Specification | Purpose |
| --- | --- |
| | |

### Policies

| Policy | Purpose |
| --- | --- |
| | |

### Commands

| Command | Effect |
| --- | --- |
| | |

### Queries

| Query | Result |
| --- | --- |
| | |

### Services

| Service class | Responsibilities |
| --- | --- |
| | |

Standards: [service-layer-template.md](service-layer-template.md).

### Validators

| Validator | Rules |
| --- | --- |
| | |

### Permissions

| Permission | Description |
| --- | --- |
| `{service}.{resource}.{action}` | |

### Events

| Event | When |
| --- | --- |
| | |

Standards: [event-template.md](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](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):

- [ ] Unit
- [ ] Repository
- [ ] Service / Command / Query
- [ ] Integration / API
- [ ] Migration
- [ ] Permission
- [ ] Security
- [ ] Architecture / Boundary
- [ ] Performance (if hot path)
- [ ] Tenant Isolation
- [ ] Documentation Validation

Standards: [testing-template.md](testing-template.md).

### Documentation

- [ ] Phase doc (this file)
- [ ] Progress / Next Steps / Roadmap as applicable
- [ ] Module Registry / Provider Registry
- [ ] Reference (API / events / schema) if public surface changed
- [ ] OpenAPI
- [ ] ADR if architectural decision introduced
- [ ] Manifests updated
- [ ] Handover completed (incl. Enterprise Completeness Sign-Off)

Standards: [documentation-template.md](documentation-template.md).

### Mandatory Artifacts Trace

Confirm each applicable row from [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md) is In Scope, Done, or N/A (justified):

- [ ] Trace completed in phase doc or handover appendix

## Out of Scope

Explicit exclusions (prevent scope creep and future-phase pull-forward):

-

## Completion Criteria

- [ ] Objective met
- [ ] Enterprise Phase Discovery Record complete; Missing→Implement gaps closed
- [ ] Business Analysis complete
- [ ] Scope delivered; Out of Scope untouched
- [ ] [Definition of Done](definition-of-done.md) satisfied
- [ ] [Enterprise Completeness](enterprise-completeness.md) signed off
- [ ] Tests green
- [ ] Quality gates passed ([quality-gates.md](quality-gates.md))
- [ ] [phase-handover.md](phase-handover.md) filled
- [ ] Boundary rules respected ([boundary-rules.md](boundary-rules.md))
- [ ] No TODO for claimed work
- [ ] Development loop completed ([development-loop.md](development-loop.md))

## Architecture Impact

-

## Database Impact

-

## Risks

-

## Related Documents

- [AI / Enterprise Framework](README.md)
- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
- [Master Prompt](master-prompt.md)
- [Definition of Done](definition-of-done.md)
- [Mandatory Phase Artifacts](mandatory-phase-artifacts.md)
- [Boundary Rules](boundary-rules.md)
- [Module Registry](../module-registry.md)
- [Architecture Overview](../architecture/architecture.md)
- [Project Principles](../development/project-principles.md)
- [Progress](../progress.md)
- [Next Steps](../next-steps.md)
- [Roadmap](../roadmap.md)