Claude-Code-Workflow/.claude/commands/ddd/doc-refresh.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
doc-refresh	Incrementally update affected documents based on changed components/features. Layer 3 → 2 → 1 selective refresh. Called by sync/update or used standalone.	[-y|--yes] [--components <id1,id2,...>] [--features <id1,id2,...>] [--minimal] [--dry-run]	TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)

Auto Mode

When --yes or -y: Auto-update affected documents without confirmation prompts.

DDD Doc Refresh Command (/ddd:doc-refresh)

Purpose

Incrementally update only the affected documents after code changes. Unlike /ddd:doc-generate (full generation), this command selectively refreshes documents for specific components and features.

affected component/feature IDs → update tech-registry (L3) → update feature-maps (L2) → update indexes (L1)

When to Use

Scenario	Use
After /ddd:sync detects code changes	doc-refresh (auto-called by sync)
After /ddd:update traces impact	doc-refresh (auto-called by update)
Manual refresh of specific component docs	doc-refresh --components tech-auth-service
Quick metadata-only update	doc-refresh --minimal --components tech-auth-service
Preview what would change	doc-refresh --dry-run --components tech-auth-service

Prerequisite

• doc-index.json must exist at .workflow/.doc-index/doc-index.json
• At least one of --components or --features must be provided (or received from caller)
• Corresponding documents must already exist (generated by /ddd:doc-generate)
• If documents missing → error: "Documents not found. Run /ddd:doc-generate first."

Phase 1: Determine Refresh Scope

1.1 Resolve Affected Entities

IF --components provided:
  affected_components = parse comma-separated IDs
  affected_features = lookup featureIds for each component in doc-index.json

IF --features provided:
  affected_features = parse comma-separated IDs
  affected_components = union of all component IDs linked to features

Merge both sets if both flags provided.

1.2 Validate Entities Exist

For each ID, verify it exists in doc-index.json. Warn and skip missing IDs.

1.3 Check Document Existence

For each affected entity, check if corresponding .md file exists:

• Missing Layer 3 doc → warn: "Component doc not found. Run /ddd:doc-generate first."
• Missing Layer 2 doc → warn: "Feature doc not found. Run /ddd:doc-generate first."

Phase 2: Layer 3 — Update Component Docs

For each affected component's tech-registry/{slug}.md:

ccw cli -p "PURPOSE: Update component documentation for {component.name} after code changes
TASK:
• Update code locations and line ranges
• Update symbol list (add new exports, remove deleted)
• Add change entry to history table
• Refresh usage examples if API changed
MODE: write
CONTEXT: @{component.codeLocations[].path}
EXPECTED: Updated markdown with current API state
CONSTRAINTS: Preserve existing structure | Only update changed sections
" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/

Update frontmatter:

---
layer: 3
component_id: tech-auth-service
generated_at: {original}
last_updated: ISO8601
---

2.1 Minimal Mode (--minimal)

With --minimal, only update:

• codeLocations in frontmatter
• last_updated timestamp
• Skip CLI call for content regeneration

Phase 3: Layer 2 — Update Feature Docs

For each affected feature's feature-maps/{slug}.md:

ccw cli -p "PURPOSE: Update feature documentation for {feature.name} after component changes
TASK:
• Update component list if new components added
• Update status if requirements now fully implemented
• Add change entry to history table
• Refresh integration guide if component APIs changed
MODE: write
CONTEXT: @.workflow/.doc-index/tech-registry/{affected-components}.md
EXPECTED: Updated markdown reflecting current feature state
CONSTRAINTS: Reference updated Layer 3 docs | Preserve business language
" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/

Update frontmatter:

---
layer: 2
feature_id: feat-auth
depends_on_layer3: [tech-auth-service, tech-user-model]
generated_at: {original}
last_updated: ISO8601
---

3.1 Minimal Mode (--minimal)

With --minimal, only update:

• Component list in frontmatter
• Feature status (if requirements mapping changed)
• last_updated timestamp
• Skip CLI call for content regeneration

Phase 4: Layer 1 — Update Index Docs (conditional)

4.1 Trigger Conditions

Condition	Action
New component registered	Update tech-registry/_index.md
Component removed	Update tech-registry/_index.md
Feature status changed	Update feature-maps/_index.md
New feature added	Update feature-maps/_index.md + README.md
Major architecture change	Update ARCHITECTURE.md
New action-log entry	Update action-logs/_index.md

4.2 Update _index.md Files

Refresh table entries for affected features/components:

• feature-maps/_index.md
• tech-registry/_index.md
• action-logs/_index.md (if new action entry)

4.3 Update Overview Docs (only if significant)

If new features added or major status changes:

ccw cli -p "PURPOSE: Update project overview docs after feature changes
TASK:
• Update README.md feature list
• Update ARCHITECTURE.md if new components added
• Update planning/_index.md with new planning sessions
MODE: write
CONTEXT: @.workflow/.doc-index/feature-maps/*.md @.workflow/.doc-index/doc-index.json
EXPECTED: Updated overview docs with current project state
CONSTRAINTS: High-level only | Link to Layer 2 for details
" --tool gemini --mode write --cd .workflow/.doc-index/

4.4 Skip Layer 1

With --minimal or when changes are minor (only code location updates): skip Layer 1 entirely.

Phase 5: Refresh Report

Document Refresh Report

Affected Scope:
  Components: {N} ({component IDs})
  Features: {N} ({feature IDs})

Updated:
  Layer 3 (Components): {N} documents refreshed
  Layer 2 (Features):   {N} documents refreshed
  Layer 1 (Indexes):    {N} documents refreshed (or "skipped")

Mode: {full|minimal}

Dry-Run Mode

With --dry-run:

• Execute Phase 1 (scope determination)
• Display what would be updated (affected files list)
• Skip all file writes (Phase 2-4)
• Output: "Dry-run complete. {N} documents would be refreshed."

Flags

Flag	Effect
-y, --yes	Auto-confirm all updates
--components <ids>	Comma-separated component IDs to refresh
--features <ids>	Comma-separated feature IDs to refresh
--minimal	Only update metadata/frontmatter, skip content regeneration
--dry-run	Preview what would change without modifying files

Integration Points

• Input from: doc-index.json, affected entity IDs (from /ddd:sync or /ddd:update)
• Called by: /ddd:sync (after change detection + index update), /ddd:update (after impact tracing + index update)
• Standalone: Can be run independently to refresh specific component/feature docs
• Prerequisite: Documents must exist (generated by /ddd:doc-generate)