phase-dependency-analysis

source	shipped
name	phase-dependency-analysis
description	Use when phase or task ordering needs dependency, overlap, or blast-radius analysis
type	colony
domains	["analysis","dependency-management","planning"]
agent_roles	["route_setter","architect","scout"]
workflow_triggers	["plan"]
task_keywords	["dependency","dependencies","ordering","parallel","blast radius"]
priority	normal
version	1.0

Phase Dependency Analysis

Purpose

Analyzes phase dependencies through three lenses -- file overlap, semantic dependencies, and data flow -- to auto-suggest optimal phase ordering. Produces a dependency graph that the roadmap-manager can use to validate or restructure the colony's execution plan.

When to Use

• aether plan is run and the roadmap has phases without explicit dependencies
• The architect suspects phases may conflict or could be parallelized
• A phase failed and the queen needs to understand blast radius
• Before reordering the roadmap to ensure valid dependency chains
• When adding a new phase to determine where it fits in the dependency graph
• During colony init to generate the initial dependency relationships

Instructions

Step 1 -- Collect Phase Data

For each phase in the roadmap:

1. Read the phase description, goal, and scope from .aether/roadmap.md
2. If PLAN.md exists, read it for task-level file paths
3. If SPEC.md exists, read it for interface contracts
4. If CONTEXT.md exists, read it for codebase context
5. Extract: expected files to create/modify, APIs to consume/expose, data models involved

Record per-phase data:

phase: {N}
title: {title}
files_expected: [{paths or glob patterns}]
apis_produced: [{interface names}]
apis_consumed: [{interface names}]
data_models: [{model names}]
shared_state: [{global state, config, env vars}]

Step 2 -- File Overlap Analysis

Compare every pair of phases for file overlap:

overlap(A, B) = |files_expected(A)  files_expected(B)| / |files_expected(A)  files_expected(B)|

Classification:

• High overlap (>0.3): Phases likely conflict. Must be sequential, or tasks must be split to avoid simultaneous file access.
• Medium overlap (0.1-0.3): Possible conflict. Review for read vs write patterns.
• Low overlap (<0.1): Unlikely to conflict. Good candidates for parallel execution.

Record overlaps:

## File Overlap Matrix

| | P1 | P2 | P3 | P4 |
|---|---|---|---|---|
| P1 | -- | H | L | M |
| P2 | H | -- | L | L |
| P3 | L | L | -- | M |
| P4 | M | L | M | -- |

Step 3 -- Semantic Dependency Analysis

Determine logical dependencies between phases:

1. Producer-Consumer: Phase A creates an API or module that Phase B uses -> A must precede B
2. Foundation-Extension: Phase A establishes a pattern or infrastructure that Phase B extends -> A must precede B
3. Independent: Neither phase references the other's outputs -> can be parallel
4. Mutually Exclusive: Phases implement alternative approaches to the same problem -> pick one

For each phase pair, classify the relationship and assign a dependency type:

pair: ({A}, {B})
relationship: {producer-consumer | foundation-extension | independent | mutually-exclusive}
direction: {A->B | B->A | none | conflict}
confidence: {high | medium | low}
reasoning: {why this relationship exists}

Step 4 -- Data Flow Analysis

Trace data dependencies between phases:

1. Identify data models each phase creates, reads, or modifies
2. Identify shared state (databases, config files, environment variables)
3. Map data flow: who creates data, who reads it, who transforms it

data_flow:
  - model: {User}
    created_by: [Phase 1]
    read_by: [Phase 2, Phase 4]
    modified_by: [Phase 3]
    implies: Phase 1 -> Phase 2, Phase 1 -> Phase 3, Phase 1 -> Phase 4

Step 5 -- Synthesize Dependency Graph

Combine all three analyses into a unified dependency graph:

nodes: [{phase numbers}]
edges:
  - from: {A} to: {B}
    type: {hard | soft | none}
    sources: [{file_overlap | semantic | data_flow}]
    confidence: {high | medium | low}

Edge types:

• Hard: Must be sequential. Derived from producer-consumer or foundation-extension relationships.
• Soft: Should be sequential but could be parallel with coordination. Derived from medium file overlap or indirect data flow.
• None: No dependency. Can run in parallel.

Step 6 -- Generate Ordering Suggestions

From the dependency graph, produce:

1. Suggested ordering: Topological sort of hard edges only
2. Parallelization opportunities: Groups of phases with no hard edges between them
3. Risk areas: Soft dependencies that could become hard if assumptions are wrong
4. Cycle warnings: Any circular dependencies detected

Output:

## Suggested Phase Ordering

### Sequential Chain (hard dependencies)
Phase 1 -> Phase 3 -> Phase 5

### Parallel Group A (no dependencies between)
Phase 2, Phase 4

### Parallel Group B (no dependencies between)
Phase 6, Phase 7 (both depend on Phase 5)

### Risk: Soft Dependencies
- Phase 2 -> Phase 4 (data_flow: shared User model, could conflict on schema changes)
  Mitigation: Phase 4 should read User model as read-only, coordinate schema changes through Phase 3

Step 7 -- Write Dependency Graph

Save the complete analysis:

# Colony Dependency Graph

## Summary
{N} phases analyzed, {X} hard dependencies, {Y} soft dependencies, {Z} parallel groups.

## Phase Data
{per-phase data from Step 1}

## File Overlap Matrix
{from Step 2}

## Semantic Relationships
{from Step 3}

## Data Flow Map
{from Step 4}

## Dependency Edges
{from Step 5}

## Ordering Suggestions
{from Step 6}

## Confidence Assessment
| Edge | Confidence | What would change it |
|------|-----------|---------------------|
| {A->B} | {H/M/L} | {evidence needed} |

Key Patterns

Three-Lens Validation

Never rely on a single analysis type. File overlap alone misses semantic dependencies. Semantic analysis alone misses data conflicts. All three must agree before marking a dependency as "none."

Confidence Escalation

Low-confidence edges should be escalated to the architect for manual review. The analyzer makes recommendations; the architect makes decisions.

Incremental Updates

When a new phase is added, don't re-anze everything. Compare only the new phase against existing ones. Update the graph incrementally.

Output Format

• .aether/context/dependency-graph.md -- full analysis
• .aether/context/dependency-matrix.json -- machine-readable overlap/edge data
• Updates to .aether/roadmap.md dependency fields (if queen approves suggestions)

Examples

Example 1 -- Simple Linear Project

4-phase project to build a CRUD app.

File overlap: low between all phases (different files). Semantic: Phase 1 (models) -> Phase 2 (API) -> Phase 3 (frontend) -> Phase 4 (tests). Data flow: models created in Phase 1 consumed by all others.

Result: linear chain. No parallelism possible. Graph confirms the obvious ordering.

Example 2 -- Parallel Opportunity

6-phase project with frontend and backend tracks.

File overlap: zero between frontend and backend phases. Semantic: Phase 1 (DB schema) is foundation for both tracks. Data flow: shared data model, but read-only on frontend.

Result: Phase 1 first, then Phase 2+3 (backend) and Phase 4+5 (frontend) in parallel. Phase 6 (integration) depends on both tracks. Significant time savings.

Example 3 -- Hidden Conflict

Phases 3 and 5 appear independent but both modify the User model schema.

File overlap: medium (shared migration files). Semantic: independent goals but shared data model. Data flow: both write to User table.

Result: soft dependency detected. Recommendation: sequential with Phase 5 reading the schema that Phase 3 establishes. Risk flagged if both try to run migrations simultaneously.