## 🔍 Phase 1: Repository & Build Context Reconstruction Objective: Understand the repository structure and identify initial optimization opportunities. Assumed repository structure: ``` monorepo/ ├── apps/ │ ├── web-store/ │ ├── admin-dashboard/ │ └── customer-portal/ ├── libs/ │ ├── shared-ui/ │ ├── design-tokens/ │ └── utilities/ ├── nx.json ├── package.json ├── tsconfig.base.json └── .github/workflows/ ``` Initial findings: - 🟡 The three applications may share libraries, but actual dependency relationships require graph evidence. - 🟡 Shared TypeScript configuration could invalidate many projects if declared as a global input. - 🟡 The 3-minute incremental build is above the 1-minute objective. - 🟡 A 55% cache-hit rate suggests an opportunity to investigate cache misses. Unknown evidence: - Actual Nx project graph. - Task execution logs. - Cache misses by task. - Whether all applications rebuild after every UI change. Verdict: Collect project graph and task timing data before modifying build boundaries. ## 🧩 Phase 2: Build Target & Package Boundary Discovery Potential issue: `shared-ui` may contain components used by multiple applications. | Finding | Assessment | | ------- | ------------------------------------------------------ | | BND-01 | Shared UI changes may affect multiple consumers | | BND-02 | Design tokens may have broad downstream impact | | BND-03 | Utility library boundaries require dependency analysis | Recommended investigation: - Inspect Nx project configuration and target definitions. - Identify each library's direct consumers. - Determine whether the build targets combine unrelated responsibilities. - Measure whether target execution time justifies splitting any library. Proposed action: Split a library only if evidence shows that independent responsibilities or dependency relationships cause unnecessary rebuilds. ## 🕸️ Phase 3: Dependency Graph Reconstruction Illustrative dependency graph: design-tokens Shared styling primitives shared-ui Reusable React components web-store Application build target The graph illustrates the supplied dependency example. Other application edges are unknown. Analysis: - 🔗 `design-tokens` may have high downstream fan-out. - 🔗 A change to `shared-ui` may require rebuilding its actual consumers. - 🔗 A dependency cycle cannot be confirmed without graph data. Next diagnostic: Generate the actual Nx project graph and inspect affected targets. ## 🔄 Phase 4: Incremental Build & Rebuild Propagation Audit Test scenario: Change one button component in `shared-ui`. | Step | Expected investigation | | ---- | ------------------------------------------- | | 1 | Identify the changed file | | 2 | Map it to `shared-ui` | | 3 | Identify downstream consumers | | 4 | Inspect selected build and test tasks | | 5 | Compare selected tasks with required tasks | | 6 | Verify whether omitted tasks remain correct | Potential inefficiency: Unrelated applications may be rebuilding because of overly broad task inputs or affected-project selection. Correctness warning: Rebuilding downstream consumers is not necessarily wasteful. Public API changes, generated outputs, and compiler dependencies may require it. Acceptance criterion: No required task is skipped, and demonstrably unrelated tasks can be excluded. ## 🧱 Phase 5: Module Coupling & Boundary Optimization Candidate change: BND-01 - Current state: One shared UI library may contain components with different consumer groups. - Proposed state: Separate independent component groups only when dependency and build measurements justify it. - Expected benefit: Potentially narrower dependency propagation. - Risk: More packages, additional configuration, and maintenance overhead. - Effort: Medium, pending repository inspection. - Validation: Compare affected targets and build duration before and after the change. Decision: Do not split `shared-ui` solely because it is large. ## ⚙️ Phase 6: Task Graph & Build Orchestration Potential issue: Build and test tasks may be partially serialized. Recommended investigation: - Identify tasks on the critical path. - Inspect duplicate prerequisite execution. - Determine whether independent application builds can execute concurrently. - Check CPU and memory usage before increasing parallelism. - Confirm that tasks do not write to shared outputs. Proposed optimization: Allow independent tasks to run concurrently when their dependencies and resource requirements permit. Success criterion: Lower wall-clock duration without task races, failed tests, or increased unnecessary work. ## 💾 Phase 7: Build Cache Effectiveness & Invalidation Illustrative supplied baseline Cache-hit rate ## 55% Cache-miss rate ## 45% Potential causes to investigate: - Incomplete or overly broad cache keys. - Different environment or toolchain inputs. - Non-deterministic build outputs. - Tasks that are not cacheable. - Cache restore overhead exceeding task execution savings. Recommended action: Analyze cache misses by task and verify that all output-affecting inputs are represented in cache keys. Important: Never remove a relevant input from a cache key just to increase the hit rate. ## 🎯 Phase 8: Affected-Project Detection | Change type | Expected selection | | ----------------------------- | ---------------------------------------------------- | | One application component | Application and genuinely required dependent tasks | | Shared UI component | Actual affected consumers and required dependencies | | Shared design tokens | Consumers whose outputs depend on the changed tokens | | Root TypeScript configuration | All projects affected by the configuration change | | Test-only file | Relevant test targets and required prerequisites | Tests to perform: - Check for false positives: unnecessary targets selected. - Check for false negatives: required targets omitted. - Validate merge-base and changed-file detection in CI. - Verify behavior for deleted and renamed files. Acceptance criterion: Every required target is selected, and unrelated targets are excluded whenever impact can be determined safely. ## 🧪 Phase 9: Determinism & Reproducibility Risk areas: - Unpinned toolchain versions. - Environment-dependent generated files. - Undeclared environment variables. - Untracked generated artifacts. - Different local and CI build environments. Validation experiment: 1. Build the same revision with a clean workspace. 2. Repeat the build using equivalent toolchain and environment settings. 3. Compare generated artifacts and relevant checksums. 4. Investigate differences before enabling additional caching. Verdict: Reproducibility is not established by the sample inputs. It must be tested. ## 🧰 Phase 10: Generated Code & Shared Configuration Potential high-impact inputs: - `tsconfig.base.json` - Root-level build scripts. - Dependency lockfiles. - Shared code-generation tools. - Global lint and formatting configuration. Recommended action: - Map each shared input to its actual dependent targets. - Confirm generator inputs and outputs are explicitly tracked. - Ensure shared configuration changes invalidate the correct tasks. - Avoid rebuilding unrelated projects when dependency metadata proves they are unaffected. Success criterion: Accurate invalidation without stale artifacts. ## 🚦 Phase 11: CI Pipeline Optimization Illustrative pipeline: Checkout & Install Affected-Project Calculation Build Tests Required Validation & Reporting Potential improvements: - Reuse dependency installation where safe. - Avoid repeated prerequisite tasks. - Parallelize independent validation tasks. - Measure cache transfer time. - Separate queue time from execution time. Constraint: The diagram represents a proposed investigation model, not the verified current CI workflow. ## 📊 Phase 12: Benchmark & Measurement Design Baseline benchmarks: | Benchmark | Measurement | | ------------------------- | ----------------------------------- | | Clean build | Wall-clock time | | Warm incremental build | Wall-clock time and tasks executed | | Cold-cache build | Cache misses and task duration | | Warm-cache build | Cache hits and restoration overhead | | Shared-library change | Affected-target count | | Root configuration change | Correct invalidation scope | | Pull-request CI | End-to-end duration | Test protocol: - Run comparable scenarios on the same runner configuration. - Repeat each scenario at least five times. - Record median duration and variability. - Keep cache state and revision consistent. - Compare both task execution count and total duration. Target: Under 60 seconds for the defined incremental-build workload. This target comes from the sample objective, not a measured forecast. ## ⚖️ Phase 13: Correctness, Security & Risk Audit | Risk | Severity | Mitigation | | ------------------------------------ | -------- | ------------------------------------------------ | | Missing dependency edge | High | Validate dependency declarations | | Incorrect cache key | High | Verify complete input fingerprints | | Incorrect affected-project selection | High | Test representative change types | | Parallel output collision | High | Enforce output ownership | | Untrusted remote cache artifact | High | Restrict cache writers and verify trust controls | | Excessive package fragmentation | Medium | Measure overhead before splitting targets | Release gate: No optimization is accepted solely because it reduces build duration. Required tests, dependency integrity, and reproducibility must remain intact. ## 🗺️ Phase 14: Proposed Optimization Blueprint OPT-01: Dependency Graph Audit First priority Effort: Low to medium Inspect actual project edges and affected-target expansion. OPT-02: Cache Miss Analysis Effort: Medium Identify high-cost misses and validate cache-key completeness. OPT-03: Task Graph Optimization Effort: Medium Reduce redundant prerequisites and safely parallelize independent tasks. OPT-04: Boundary Refactoring Effort: Medium to high Refactor only the boundaries linked to measured rebuild problems. ## 🛠️ Phase 15: Implementation Roadmap 1. Stage A: Establish the baseline - Capture clean and incremental build logs. - Export the actual dependency graph. - Record task timings and cache statistics. Acceptance: Reproducible baseline measurements. 2. Stage B: Correct dependency declarations - Inspect missing and unnecessarily broad dependencies. - Fix configuration inputs and output declarations. Acceptance: Graph and dependency validation pass. 3. Stage C: Improve caching and incremental builds - Investigate high-cost cache misses. - Test affected-project selection. - Validate generated artifact invalidation. Acceptance: Correct outputs with less unnecessary work. 4. Stage D: Optimize boundaries and scheduling - Implement evidence-backed boundary changes. - Parallelize independent tasks where safe. Acceptance: Reduced measured critical-path duration. 5. Stage E: Enforce regression guardrails - Add performance benchmarks. - Validate clean and incremental builds in CI. - Establish rollback procedures. Acceptance: Performance gains persist without correctness regressions. ## 🏆 Phase 16: Final Engineering Report ### A. Executive Summary The illustrative monorepo has an 8-minute clean build, a 3-minute incremental build, and a 55% cache-hit rate. The immediate goal is an incremental build under 60 seconds. The strongest initial strategy is to measure dependency propagation, affected-project selection, and cache misses before refactoring modules. ### B. Evidence Register - Supplied sample facts: Build times, cache-hit rate, runner size, and stated dependency example. - Derived fact: The incremental build must become at least 120 seconds faster to meet the 60-second objective. - Unknown: Actual project graph, per-task timings, cache-miss causes, and CI critical path. - Assumption: The sample directory structure and pipeline diagram are illustrative. ### C. Prioritized Optimization Register | ID | Priority | Expected value | Confidence | | ------ | -------- | ----------------------------------------- | ------------------ | | OPT-01 | P0 | Establish actual rebuild scope | High | | OPT-02 | P1 | Identify cache optimization opportunities | Medium | | OPT-03 | P1 | Reduce avoidable scheduling overhead | Medium | | OPT-04 | P2 | Reduce unnecessary coupling | Low until measured | ### D. Before-versus-After Targets | Metric | Baseline | Acceptance target | | ----------------- | -------- | ----------------------------------------------------- | | Clean build | 8 min | Measure; no arbitrary target | | Incremental build | 3 min | Under 1 min | | Cache-hit rate | 55% | Improve after diagnosis | | Build correctness | Unknown | All required checks pass | | Reproducibility | Unknown | Equivalent inputs produce verified equivalent outputs | ### E. Final Engineering Verdict 1. Most important bottleneck to investigate: Why a small UI change takes three minutes to build. 2. Strongest first optimization: Accurate dependency-aware affected-project selection, supported by actual task logs. 3. Highest-risk boundary change: Splitting shared libraries before confirming dependency and ownership relationships. 4. First experiment: Record all tasks triggered by one isolated `shared-ui` component change. 5. Critical correctness risk: Missing a required downstream build or omitting an output-affecting cache input. 6. Success definition: Incremental build below 60 seconds for the agreed benchmark, all required tests passing, correct artifacts, and no regression in reproducibility. ## ✅ Sample Test Result 16-phase structure completed All seven inputs applied Findings, risks, roadmap, and acceptance criteria included Repository-level validation pending Overall verdict: The prompt produces a structured, evidence-conscious engineering blueprint. To verify real optimization recommendations, run it with actual repository configuration, dependency graphs, build logs, and cache statistics rather than illustrative inputs.