codd-propagate

name	codd-propagate
description	Reverse-propagate source code changes back to affected CoDD design documents. Use after code changes when the user needs to map changed source files to modules, identify impacted design docs, and optionally update those docs while preserving CoDD coherence.

CoDD Propagate

Reverse-propagate source code changes to design documents. When source code changes, codd propagate identifies which design docs are affected via the modules field and optionally updates them using AI.

When to Use

• After modifying source code and before committing
• When you want to check which design docs are affected by code changes
• When you want to auto-update design docs to reflect code changes
• As part of the modification flow (code changed → propagate → review → commit)

Do NOT use this for:

• Document-to-document propagation — use /codd-impact instead
• Initial design doc generation — use /codd-generate (greenfield) or /codd-restore (brownfield)

Propagation Direction

CoDD supports two propagation directions:

Direction	Command	Trigger	Mechanism
Forward (doc → doc)	codd impact	Design doc changed	CEG dependency graph (depends_on)
Reverse (code → doc)	codd propagate	Source code changed	modules field in frontmatter

/codd-propagate handles the reverse direction only.

How It Works

git diff HEAD              # 1. Detect changed source files
  ↓
source_dirs mapping        # 2. Map files to modules (e.g. src/auth/service.py → "auth")
  ↓
modules field lookup       # 3. Find design docs with matching modules
  ↓
Analysis report            # 4. Show which docs need attention
  ↓ (--update only)
AI update                  # 5. AI updates affected doc bodies

Prerequisite Checks

Before running propagate, verify:

1. codd/codd.yaml exists with source_dirs configured in scan.
2. Design docs have modules field in their frontmatter.
3. There are uncommitted source code changes (or specify --diff target).
4. Confirm you are in the intended project root.

If modules fields are missing, run codd plan --init to regenerate wave_config with modules, then regenerate or restore design docs.

Recommended Workflow

Analysis Only (Default)

codd propagate --path .

This shows:

• Changed source files and their module mappings
• Design docs affected by those changes
• Suggestion to run with --update if updates are needed

Review the analysis before deciding whether to update.

With AI Update

codd propagate --path . --update

This additionally:

• Calls AI to update each affected design doc body
• Preserves frontmatter exactly as-is
• Leaves doc body unchanged for bug fixes or refactoring that don't affect design

After update, review every changed document before committing.

HITL Gates

1. After analysis: Review the file → module → doc mapping. Confirm the affected docs list is correct before running with --update.
2. After update: Read every updated design doc. Confirm:
   • Changes accurately reflect the code modification
   • No unrelated sections were altered
   • Bug fixes / refactoring correctly left the doc body unchanged
   • Frontmatter was preserved exactly

When NOT to Update

Not every code change needs a design doc update. The AI prompt explicitly tells the model to leave the body unchanged for:

• Bug fixes that don't change the design
• Minor refactoring (rename, extract method)
• Performance optimizations that don't change architecture
• Test additions or modifications

Use analysis-only mode (codd propagate without --update) to check which docs are affected, then decide manually whether an update is warranted.

Options

Flag	Description
--path	Project root (default: current directory)
--diff	Git diff target (default: HEAD)
--update	Actually update affected docs via AI (default: analysis only)
--ai-cmd	Override AI command for this run

Complete Modification Flow

After modifying source code:

# 1. Check reverse impact (code → docs)
codd propagate --path .

# 2. If design docs need updating
codd propagate --path . --update

# 3. Rebuild dependency graph
codd scan --path .

# 4. Check forward impact (doc → doc) if design docs changed
codd impact --path .

# 5. Validate and commit
codd validate --path .
git add -A && git commit

Troubleshooting

• No changed files detected
  • Ensure you have uncommitted changes, or specify a different --diff target (e.g. --diff HEAD~3).
• No affected design docs found
  • Check that source_dirs is configured in codd.yaml → scan.
  • Check that design docs have modules fields in their frontmatter.
  • Verify the module names match (e.g. src/auth/service.py maps to module auth).
• Updated doc body is empty or garbled
  • Re-run with --update. If the AI output is still bad, manually edit the doc.

Guardrails

• Use the codd command, not python -m codd.cli.
• Always run analysis first (without --update) to confirm affected docs before updating.
• Do not skip human review of updated documents.
• Do not combine with codd impact in the same step — propagate handles code→doc, impact handles doc→doc.
• After propagate with --update, always run codd scan to refresh the dependency graph.