TorbatYar/docs-runtime/ai-framework/enterprise-phase-discovery.md

Enterprise Phase Discovery

Mandatory pre-implementation process for every phase.

Before writing production code for a phase, the Framework MUST automatically perform Enterprise Phase Discovery. Discovery determines the complete responsibility of the current phase and derives every missing production-ready capability inside that phase boundary.

This rule extends ADR-018 via ADR-019. Companions: definition-of-done.md · mandatory-phase-artifacts.md · boundary-rules.md · enterprise-completeness.md.

Absolute Rules

1. Discovery runs before Implementation (and before Domain Modeling finalizes the build list).
2. Never assume CRUD is sufficient.
3. Automatically derive every missing production-ready capability required for the current phase.
4. If anything required for the current phase is missing, it MUST become part of the implementation before Complete.
5. Never move responsibilities from future phases.
6. Never violate Service Boundaries (boundary-rules.md).
7. Never duplicate another service.

Discovery Inputs (mandatory sources)

The agent must inspect and synthesize all of the following that exist for the phase’s service/area:

Input	Where to look
Current Roadmap	roadmap.md, area roadmaps (*-roadmap.md), phase-manifest.yaml, next-steps.md
Current Architecture	docs/architecture/*, docs/architecture/adr/*
Service Boundaries	module-boundaries.md, module-registry.md, service-manifest.yaml
Previous Phase Handover	docs/phase-handover/*, prior phase docs
Existing Codebase	backend/services/<name>/ (or owning path) — models, services, repos, APIs, tests
Existing APIs	Routers, OpenAPI, api-reference.md, services-contracts.md
Existing Domain Model	Models, schemas, validators, phase domain sections
Existing Events	app/events/, outbox, event-catalog.md
Existing Permissions	app/permissions/, registry permission trees
Existing Aggregates	Models + service ownership docs
Existing Tests	app/tests/, pytest suites
Existing Documentation	Phase docs, service README, registries, progress

Docs-only / registration-only phases still run Discovery against documentation and manifests (codebase may be N/A).

Discovery Procedure

1. Load context — Read framework docs, then every Discovery Input above for the current phase.
2. State phase boundary — Objective, In Scope, Out of Scope, owning service(s), forbidden foreign ownership, next-phase exclusions.
3. Inventory baseline — Record what already exists (aggregates, APIs, events, permissions, tests, docs, ops surfaces).
4. Derive target responsibility — From roadmap + architecture + handover + boundaries, state the complete capability set this phase must own when Complete.
5. Gap analysis — Diff baseline vs target using the Missing Capability Checklist below.
6. Promote gaps to Scope — Every gap that belongs to this phase becomes mandatory implementation work (not a TODO, not a “limitation”).
7. Reject illegal gaps — Gaps owned by another service → integrate via API/Events/Providers only. Gaps owned by a future phase → leave Out of Scope.
8. Publish Discovery Record — Write the Enterprise Phase Discovery section into the phase doc (see template) before coding.
9. Gate — Architecture Validation and Implementation may proceed only after the Discovery Record is complete.

Missing Capability Checklist

Identify missing items for the current phase (mark Present / Missing→Implement / N/A justified / Future-phase / Other-service):

Capability class	Examples
Business Capabilities	End-to-end use cases, not mere table CRUD
Entities	ORM/domain entities for in-scope data
Value Objects	Money, codes, periods, identifiers as needed
Aggregates	Consistency boundaries and invariants
Services	Domain orchestration
Policies	Authz / entitlement / domain policies
Specifications	Reusable predicates / query specs
Repositories	Tenant-scoped persistence
Commands	State-changing use cases
Queries	Read use cases without write side-effects
REST APIs	Resource endpoints for in-scope capabilities
Capability APIs	/capabilities or equivalent
Permission APIs / tree	{service}.* registration and checks
Health APIs	/health
Metrics	/metrics or justified ops alternative
Events	Outbox domain/integration events
Background Jobs	Async/scheduled work when required
Configurations	Env/settings keys
Feature Flags	Gated capabilities when required
Provider Interfaces	Protocols for external systems
Validation Rules	Edge + domain validators
Audit	Trail for state-changing actions
Search	Collection search
Filtering	Collection filters
Sorting	Stable sort keys
Pagination	Page/cursor meta
Soft Delete	Master/business record policy
Optimistic Locking	When concurrency risk exists
Tenant Isolation	Schema, queries, APIs, tests
Documentation	Phase, registries, OpenAPI, handover
Tests	Unit, integration, architecture, security, tenant, etc.
Operational Readiness	Health, metrics/logging, config, jobs
Developer Experience	README, clear errors, runnable tests

Discovery Record (required in phase doc)

## Enterprise Phase Discovery

| Field | Value |
| --- | --- |
| Phase ID | |
| Owning service(s) | |
| 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 |
| --- | --- | --- |
| ... | Present / Missing / N/A / Future / Other-service | Implement / Skip-justify / Integrate / Defer |

### 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

Relationship to Other Framework Stages

Stage	Relationship
Business Analysis	Discovery includes and extends BA with codebase/API/test inventory
Architecture Validation	Uses Discovery boundary conclusions
Domain Modeling	Models only what Discovery promoted into scope
Implementation	Must cover every Discovery gap marked Missing→Implement
Enterprise Completeness / Quality Gates	Fail if Discovery was skipped or gaps remain unimplemented
Definition of Done	Incomplete without a Discovery Record for implementation phases

Failure Policy

Situation	Action
Discovery skipped	Phase incomplete — run Discovery before claiming progress
Gap marked Missing but not implemented	Must implement before Complete
Agent “assumes CRUD enough”	Fail Business Completeness + Discovery gates
Gap belongs to future phase	Document under Excluded; do not implement
Gap belongs to another service	Integrate only; do not re-implement

Related Documents

• Development Loop
• Definition of Done
• Mandatory Phase Artifacts
• Enterprise Completeness
• Boundary Rules
• Quality Gates
• Phase Template
• ADR-019