# Phase 3 AI-Assisted Current State Documentation
## AI-assisted resource mapping
This phase transforms the flat CSV data from Phase 2 into a connected knowledge layer. AI reads across hundreds of CSVs in `sources/current-state-inventory/` simultaneously to classify resources into business domains, identify relationships between components, and write architectural descriptions — work that would otherwise require days or weeks of manual effort.
The output of this phase is not the deliverable itself — it is the relationship and context layer that AI and consultants will use in Phase 4 to fill out the actual acceptance criteria documents. AI-generated context (resource summaries, relationship docs, Mermaid diagrams) is written back into `sources/current-state-inventory/` next to the data it describes. Enriched inventory CSVs go into the `excel-template/` folders under each user story.
AI analyzes DevOps pipelines first because the cloud resource enrichment needs to cross-reference which pipeline deploys each resource.
### Define Business Domains
After Phase 2 provides the raw inventory CSVs, AI can identify the actual business domains from resource names, tags, and naming patterns.
#### AI prompt:
```
Read the raw inventory CSVs and platform overview to define business domains.
CONTEXT:
- Platform Overview: sources/provided-docs/platform-overview.md
- Raw Inventories: sources/current-state-inventory/[cloud]/cloud-envs/*/csv-data/
(specifically: all-resources.csv, resource-tags.csv from each subscription)
Create sources/domains.csv with columns:
Domain, Covers, Resource Patterns, Pipeline Patterns.
Identify major business domains by analyzing resource names, tags, and resource
group naming patterns across all subscriptions. Common domains for data platform
migrations: Data Engineering, Data Science, Data Analytics, Platform Operations,
plus customer-specific business domains.
For each domain, list:
- What it covers (brief description)
- Resource naming patterns (regex patterns that identify resources in this domain)
- Pipeline patterns (DevOps folder paths associated with this domain)
```
Output:
```
sources/domains.csv
```
### DevOps Pipeline Analysis
Run this before cloud resource analysis. First, enrich the pipeline inventories with Domain, Purpose, and Deploys To so that the cloud resource enrichment can cross-reference which pipeline deploys each resource.
#### AI prompt:
```
Analyze DevOps pipeline data, create distilled inventory CSVs, and enrich
each pipeline with Domain, Purpose, and deployment target.
CONTEXT:
- Raw Data: sources/current-state-inventory/[cloud]/devops-envs/[project]/csv-data/
- Platform Overview: sources/provided-docs/platform-overview.md
- Domain Definitions: sources/domains.csv
STEP 1: CREATE DISTILLED INVENTORY CSVs
Read source pipeline CSVs. Create distilled inventories with enriched columns:
- inventory-01-build-pipelines.csv
Columns: Name, AzureDevOpsProject, Environment, Domain, Purpose, Deploys To,
Build Pattern, Repository, Id, Folder, Revision, Component, raw_scrape_origin
- inventory-02-pipeline-details.csv (PipelineName, Repo, YamlPath, ConfigType)
- inventory-03-build-definitions.csv (Name, Path, Type, Repo, Environment, TaskCount)
- inventory-04-repositories.csv (Name, DefaultBranch, Size, PipelineCount)
Plus trigger, task, variable, release, and integration inventories.
For each pipeline row, determine:
- Environment: extract from pipeline name (Dev, NonProd, PreProd, Prod, Other)
- Domain: assign using patterns from sources/domains.csv
- Purpose: specific description of what this pipeline does
- Deploys To: which cloud resources this pipeline deploys
- Build Pattern: the build/deploy pattern (e.g., Terraform IaC, Node.js Build, Databricks Artifact)
- Component: logical component folder grouping
- raw_scrape_origin: trace back to source CSV and row number
STEP 2: CREATE PIPELINE RELATIONSHIP DOCS
Create pipeline-relationships.md containing:
- Component → resource mapping (which pipelines deploy which resources)
- Architecture layer assignments
- Domain groupings
- Pipeline pattern analysis (common task sequences, build patterns)
- Component summary (folder groupings, pipeline counts, environments)
RULES:
- Distill, don't copy — inventory CSVs are summaries, not raw dumps
- No migration planning or recommendations — document what exists
```
Output:
```
sources/current-state-inventory/[cloud]/devops-envs/
pipeline-relationships.md # Patterns, component summary, resource mapping
work-breakdown/[epic]/[devops-user-story]/excel-template/
inventory-01-build-pipelines.csv # Enriched: Environment, Domain, Purpose, Deploys To, Build Pattern, raw_scrape_origin
inventory-02-pipeline-details.csv
inventory-03-build-definitions.csv
inventory-04-repositories.csv
inventory-05-build-triggers.csv
...
```
### Cloud Resource Analysis
After you enrich pipeline inventories, AI can analyze cloud resources and cross-reference which pipeline deploys each resource.
#### AI prompt:
```
Analyze cloud subscriptions to identify data platform resources, document
relationships, populate inventory templates, and enrich each resource with
Domain, Purpose, Environment, and Deployed By.
CONTEXT:
- Platform Overview: sources/provided-docs/platform-overview.md
- Domain Definitions: sources/domains.csv
- Cloud Subscriptions: sources/current-state-inventory/[cloud]/cloud-envs/
- Subscription Mapping: sources/current-state-inventory/[cloud]/cloud-envs/subscription-mapping.csv
- Pipeline Inventories: work-breakdown/[epic]/[devops-user-story]/excel-template/inventory-01-build-pipelines.csv
- Pipeline Relationships: sources/current-state-inventory/[cloud]/devops-envs/pipeline-relationships.md
STEP 1: IDENTIFY RELEVANT SUBSCRIPTIONS
For each subscription: read resource-tags.csv for platform-specific tags, then
all-resources.csv for naming patterns. Track which subscriptions have platform
resources and which don't.
STEP 2: DOCUMENT SUBSCRIPTION RELATIONSHIPS
For each relevant subscription, create resource-summary.md (in the subscription
folder, next to csv-data/) containing: overview, resource inventory grouped by
type, Mermaid relationship diagram from dependency data, architecture layer
mapping, and key observations.
STEP 3: POPULATE AND ENRICH INVENTORY CSVs
From each relevant subscription, populate inventory CSVs. For each resource row:
- Environment: determine from subscription name or resource naming pattern
- Domain: assign using patterns from sources/domains.csv
- Purpose: specific description including function and connections
(e.g., "Portal UI (Node.js 18) - production web interface
for data source registration" not "application service")
- Deployed By: cross-reference pipeline-relationships.md and
inventory-01-build-pipelines.csv to find which pipeline deploys this resource.
Format: pipeline-name | [DevOps](url) | [inventory-01-build-pipelines.csv, row N](path)
- raw_scrape_origin: trace back to source CSV and row number
For data-layer resources (data lakes, databases, ETL services like ADF /
Databricks / Airflow, BI sources), additionally enrich with:
- Reads From: upstream data sources this resource consumes (other tables,
storage paths, external APIs). Source from repository contents and IaC
captured in DevOps extraction CSVs, plus dependencies.csv.
- Writes To: downstream targets this resource produces (tables, storage
paths, reports). Same sources as Reads From.
- Schedule: cron expression, trigger type, or event-based trigger that
invokes this resource. Source from build-definition-triggers.csv,
release-triggers.csv, Databricks job definitions, or DAG schedules in
repository source.
- Owner: responsible team or individual. Source from rbac-assignments.csv,
resource tags, or repository CODEOWNERS.
When the source data does not contain enough detail to populate one of these
columns, leave it blank rather than inferring — sub-resource depth is added
later via on-demand extraction (see Phase 2 "On-Demand Sub-Resource Extraction").
RULES:
- Analyze subscriptions ONE AT A TIME
- Complete each step before starting the next
- Every resource name must exist in the corresponding source CSV
- Purpose must be specific — include the technology, version, and function
```
Output:
```
sources/current-state-inventory/[cloud]/cloud-envs/
resource-relationships.md # Cross-subscription relationship view
[sub-name]/resource-summary.md # Per-subscription: inventory, Mermaid diagram, architecture mapping
work-breakdown/[epic]/[resource-user-story]/excel-template/
inventory-01-app-services.csv # Enriched: Environment, Domain, Purpose, Deployed By, raw_scrape_origin
inventory-02-storage-accounts.csv
inventory-03-key-vaults.csv
inventory-04-certificates.csv
inventory-05-log-analytics-workspaces.csv
inventory-06-metric-alerts.csv
inventory-07-service-principals.csv
...
```
At this point, AI has built a rich understanding of *what* exists and *how* components relate. But it is missing *why* things are the way they are, *how* teams actually operate, and *what decisions teams made.* That knowledge lives in people's heads and meeting recordings. Phase 4 makes it accessible to AI — and then uses all of it to fill out the actual deliverable documents.