- Purpose
- What Consolidation Is — and Is Not
- Inputs to Consolidation
- Who Performs Consolidation
- When Consolidation Occurs
- The Consolidation Decision Space
- Scope of Consolidation
- Consolidation and Authority
- Consolidation as a Gate
- Common Failure Modes
- Minimal Discipline, Maximum Effect
- Status of This Document
Consolidation is the process by which learning captured during development is reviewed, validated, and — when appropriate — integrated into authoritative context documents.
Consolidation exists to answer one question:
What, if anything, must change in our shared understanding as a result of what we just learned?
Without consolidation:
- learning remains local
- context drifts silently
- future work is based on outdated assumptions
Consolidation is therefore non-optional at commitment points.
- a deliberate, human-led judgment process
- selective rather than exhaustive
- focused on impact to shared context
- accountable and reviewable
- automatic propagation of learning
- approval of code changes
- retrospective storytelling
- bulk documentation updates
Learning does not become authoritative by being written down. It becomes authoritative only through consolidation.
The primary inputs are learning artifacts produced during development.
A learning artifact may include:
- invalidated assumptions
- newly discovered constraints
- refined domain concepts
- architectural tensions
- mismatches between specification and behavior
Learning artifacts are defined in LEARNINGS.md.
Additional inputs may include:
- code changes
- specifications
- test results
- architectural discussions
However, learning artifacts are the trigger. Without them, consolidation has no explicit object.
Consolidation must be performed by humans.
This responsibility cannot be delegated to AI agents.
The consolidator:
- evaluates the validity of the learning
- assesses its implications
- decides whether and how context should change
The consolidator may be:
- a tech lead
- an architect
- a senior developer
- or a designated context owner
What matters is authority over context, not job title.
Consolidation may occur at any time, but becomes mandatory at commitment points.
Typical commitment points include:
- merging significant changes
- preparing a release
- handing work to another contributor or agent
- extending existing behavior
At a commitment point:
- relevant learning artifacts must be reviewed
- consolidation must either occur or be explicitly deferred
- known inconsistencies must be addressed
Proceeding without consolidation at a commitment point is a stop condition.
Consolidation is not required immediately. Learning may remain unconsolidated between commitment points as long as:
- it is tracked in a learning artifact
- it does not contradict active specifications or context
- it does not block other work in progress
At the next commitment point, all unconsolidated learning must be reviewed and processed (integrated, rejected, deferred, or reframed).
For each learning artifact, consolidation results in one of four outcomes:
The learning is:
- accepted as valid
- incorporated into one or more context documents
Examples:
- updating DOMAIN.md to refine terminology
- revising CONTEXT.md to reflect a discovered constraint
- adjusting SPEC.md to match observed behavior
This is the most common outcome.
The learning is:
- reviewed
- found to be incorrect, irrelevant, or misleading
- explicitly rejected
Rejection is a valid and important outcome.
Rejected learning should be:
- marked as rejected
- optionally annotated with rationale
Silent rejection is not allowed.
The learning is:
- potentially valid
- but not actionable yet
Reasons for deferral may include:
- insufficient evidence
- competing priorities
- pending decisions elsewhere
Deferred learning must be:
- explicitly marked
- revisited at a later commitment point
Indefinite deferral is a failure mode.
The learning is:
- valid in substance
- but mis-scoped or mis-expressed
In this case:
- the learning is reformulated
- and then integrated, rejected, or deferred
Reframing acknowledges that discovery and articulation are different skills.
Consolidation focuses on shared context, not local optimizations.
Typical consolidation targets include:
- DOMAIN.md
- CONTEXT.md
- ARCHITECTURE.md
- SPEC.md
- PLAN.md
- DESIGN_WORLDVIEW.md (if present)
Consolidation does not require:
- documenting implementation details
- preserving the history of discovery
- explaining every line of code
Only learning with implications beyond the immediate change belongs in context.
Consolidation changes authoritative documents.
Therefore:
- changes must be explicit
- rationale must be inspectable
- responsibility must be clear
If multiple context documents are affected, they must be updated coherently.
Partial consolidation that introduces new inconsistencies is a failure.
At commitment points, consolidation functions as a Consistency Gate, as defined in CDE.
The gate is passed only when:
- learning artifacts have been processed
- context documents are internally consistent
- known contradictions are resolved or explicitly recorded
The gate exists to protect downstream work, not to slow development arbitrarily.
Common consolidation failures include:
-
Rubber-stamping
Learning is “accepted” without real evaluation. -
Avoidance
Consolidation is postponed indefinitely. -
Over-consolidation
Low-impact learning bloats context documents. -
Authority drift
Context is changed by people without ownership.
CDDW makes these failures visible, but does not prevent them automatically.
Consolidation is intentionally lightweight.
A valid consolidation may involve:
- a small textual change
- a brief rationale
- or even a single clarified sentence
What matters is explicit alignment, not volume.
If consolidation feels heavy, it often signals that too much learning is being deferred.
This document defines the intended behavior of consolidation in CDDW.
It is expected to evolve as:
- real projects expose edge cases
- teams calibrate their tolerance for risk
- failure modes become clearer
Changes should favor clarity and accountability over convenience.
Consolidation is where learning becomes meaning.