awslabs / awslabs/aidlc-workflows

[Feature]: Propagate build-time discoveries (rate limits, API quirks, pivots) across units, independent of declared dependencies

Open
#299 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
4.6k
Forks
827
Avg merge
1d 21h
Merged PRs (30d)
165

Description

## Description

Construction runs as a per-unit loop. Today, cross-unit context is shared **only** by following the *statically declared* dependency matrix (`unit-of-work-dependency.md`, produced back in Units Generation). That matrix captures **design-time** dependencies.

**Runtime discoveries** made *while building* a unit — undocumented rate limits, API quirks, environment constraints, or pivots that weren't foreseeable at design time — never appear in that matrix. A unit that touches the same external resource **without a declared dependency** loads none of the prior unit's findings, so its agent repeats the same investigation and the same pivot independently.

This is a different layer from the static dependency graph: the graph models *who-depends-on-whom by design*, while this is about *what-was-learned-at-build-time that crosses unit boundaries regardless of declared dependencies*. The two are orthogonal — this proposal adds a layer on top of the dependency matrix, it does not change it.

> **Origin & attribution.** This was raised by @mayakost while reviewing #276. We agreed there that it is orthogonal to that PR (a session-resume path fix) and deserves its own issue. The example below is @mayakost's, carried over verbatim; filing on their behalf with credit as co-reporter.

## Use Case

A static dependency graph cannot represent build-time discoveries by design, so without a dedicated channel the same external-resource lesson gets re-learned (and re-paid-for in tokens, time, and risk of an *inconsistent* second pivot) by every unit that independently touches that resource.

**Concrete example (from @mayakost):**

> Unit 1 is a Notification module. While building it, the agent tries to use the platform's email API v2, discovers it's rate-limited to 10 req/s (undocumented), and pivots to batching with API v1. Unit 2 is a User Onboarding module that also sends emails. Since it has no connection to Unit 1, that context is never loaded because it only loads its own unit, so the agent independently tries API v2, hits the same wall, and has to repeat the same discovery and pivot.

Beyond the wasted re-discovery, there's a correctness risk: nothing guarantees Unit 2 pivots the *same* way Unit 1 did, so two units can end up integrating with the same external resource through divergent, mutually inconsistent approaches.

## Version

v1 (current)

## Area

Construction phase rules

## Additional Context

### Expected vs. actual behavior

- **Actual**: each unit loads its own artifacts plus the artifacts of its *declared* dependency units. Cross-cutting lessons learned at build time do not propagate to later units.
- **Expected**: a discovery made while building one unit that affects work beyond that unit's boundary (external API constraints, rate limits, an adopted/rejected approach and the reason) is recorded once and is visible to every later unit's build, independent of the declared dependency graph.

### Proposed direction (for discussion — not a finished design)

1. **A cross-unit discovery log**, e.g. `aidlc-docs/construction/cross-unit-discoveries.md`. One append-only entry per discovery: *finding · scope of impact · action taken · rationale · originating unit*.
2. **Load it at the start of every unit** in the per-unit loop, alongside own-unit and declared-dependency artifacts. This is a one-line addition to the "Code Stages" loading rule in `common/session-continuity.md` (the same section #276 just touched), so it also covers resumed sessions.
3. **A recording step** in `construction/code-generation.md` (Generation phase): when a unit hits an external-resource constraint or makes an unforeseen pivot, append an entry to the discovery log.
4. The dependency matrix (`unit-of-work-dependency.md`) **stays unchanged** as a design-time artifact. This mechanism is an orthogonal layer on top.

### Relationship to existing issues

- This is narrower and more concrete than **#117** (general "can multiple teams collaborate"). That asks about *design-time* team/unit coordination; this is specifically about *build-time discovery propagation* between units that may have no declared relationship at all.
- It is complementary to **#269** (archiving cycle-specific docs to avoid stale context): #269 is about *removing* stale context across cycles, this is about *carrying forward* still-relevant lessons within a single Construction cycle.
- It does not overlap with **#72** (unit context in `audit.md` logging) — that's traceability of the audit trail, not a context-loading channel for the build.

### Scope note

The change reaches into `common/` (a shared file), so per CONTRIBUTING's *Single source of truth* / *Be reproducible* tenets I'd like the approach agreed here before merging anything. I'll open a draft PR alongside this issue so the proposal is concrete and reviewable, but it's explicitly a **discussion starter** — happy to revise the mechanism (file location, where the log lives, whether it belongs in the per-unit loop vs. a smart-context rule) or to escalate to the RFC template if maintainers feel this is design-level rather than a small enhancement.

Contributor guide

Open the contributing guide

Research direction

Start by reading unit-of-work-dependency.md, common/session-continuity.md, and construction/code-generation.md to understand the existing dependency loading and generation rules. Compare the proposed cross-unit discovery log with the per-unit loop and resumed-session path. Done means the maintainers agree on the mechanism and the relevant construction rules consistently record and load still-relevant discoveries.

Written by the indexing model from the issue text.

Assessment

Domain
developer-experience, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.