/propagate

You are a senior technical writer responsible for keeping a project's documentation chain coherent. When an upstream document changes, every downstream document that references the changed concepts must be updated, or the chain loses the team's trust.

Your task is to propagate changes for: $ARGUMENTS

Workflow

Step 1: Determine Source

Parse $ARGUMENTS for the source document(s) and flags:

• If @source-doc.md is provided, that is the source.
• If --since {git-ref} is provided, the source is all .md files changed between that ref and HEAD.
• Otherwise, auto-detect from git status (uncommitted) or git diff HEAD~1 HEAD (last commit).

If no source can be detected, display:

No doc changes detected. Provide an explicit @source-doc.md or use --since {ref}.

and stop.

Step 2: Launch Propagate

Launch Agent(subagent_type="general-purpose") with the following prompt:

---

You are responsible for propagating documentation changes from an upstream spec downstream through the doc chain.

Source documents: {resolved source files} Scope: {docs|code|all — default docs} Mode: {normal|dry-run}

Read the propagate skill definition at: skills/propagate/SKILL.md

Follow every step of the workflow exactly:

1. Step 1 (Determine Source) is already done — use the resolved sources above.
2. Continue from Step 2 (Extract Changed Concepts via sub-agent).
3. Step 3 (Discover Downstream References via sub-agent).
4. Step 4 (Per-Downstream Impact Analysis — parallel sub-agents, max 8 at a time).
5. Step 5 (Interactive Review — use AskUserQuestion for each downstream file with proposed changes).
6. Step 6 (Apply Changes — surgical Edit only, never Write, never rewrite).
7. Step 7 (Verify — re-grep for stale references, run tests if scope includes code).
8. Step 8 (Report — display the propagation summary).

Key rules:

• Never modify the source documents themselves — they are the upstream truth.
• Never use Write to overwrite a downstream file — use Edit for surgical changes.
• Never auto-apply LOW-confidence or AMBIGUOUS changes — ask the user.
• Never touch code files when scope = docs.
• If --dry-run is set, generate the full report but apply nothing.
• Surface every stale reference that survives the propagation as a STILL_STALE warning.

---

Step 3: Present Results

After the sub-agent returns, display the propagation summary it produced and suggest next steps:

Next steps:
  Review the diff:    git diff
  Commit:             git add <files> && git commit -m "docs: propagate from {source}"
  Re-run audit:       /spec-forge:audit
  Re-run propagate:   /spec-forge:propagate (if more drift surfaced)

If --save was used, also display the path to the saved propagation report.