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

---
name: doc-refresh
description: Incrementally update affected documents based on changed components/features. Layer 3 → 2 → 1 selective refresh. Called by sync/update or used standalone.
argument-hint: "[-y|--yes] [--components <id1,id2,...>] [--features <id1,id2,...>] [--minimal] [--dry-run]"
allowed-tools: 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`:

```bash
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:
```markdown
---
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`:

```bash
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:
```markdown
---
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:

```bash
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`)