refresh-docs

What this skill does

# Refresh Docs

Incrementally update reverse-engineering docs from git changes. No full regeneration needed.

**Estimated Time:** 2-15 minutes (depends on change volume)
**Prerequisites:** Reverse-engineering docs exist with `.stackshift-docs-meta.json`
**Output:** Updated docs in `docs/reverse-engineering/` with refreshed commit hash

---

## Arguments

| Argument | Values | Default | Description |
|----------|--------|---------|-------------|
| mode | `smart`, `full` | `smart` | `smart` = incremental update of affected docs only. `full` = regenerate all 11 docs via `/stackshift.reverse-engineer`. |

Auto-detect `full`: if >60% of source files changed, major version bumps in package.json/go.mod, new top-level directories added, or framework migration detected, recommend `full` mode to the user.

---

## When to Activate

Activate when the user says any of:
- "Update the reverse-engineering docs"
- "Refresh the docs"
- "Sync docs with latest code"
- "What changed since docs were generated?"
- "Are the docs out of date?"

Also activate when: reverse-engineering docs exist, code has changed since they were generated, and the user wants to keep docs current without full regeneration.

---

## Process

### Step 1: Read Metadata and Validate Git State

Log: "Step 1: Reading metadata and validating git state..."

```bash
META_FILE="docs/reverse-engineering/.stackshift-docs-meta.json"

if [ ! -f "$META_FILE" ]; then
  echo "ERROR: No metadata file found. Run /stackshift.reverse-engineer first."
  exit 1
fi

PINNED_HASH=$(cat "$META_FILE" | jq -r '.commit_hash')
CURRENT_HASH=$(git rev-parse HEAD 2>/dev/null)

if [ $? -ne 0 ]; then
  echo "ERROR: git rev-parse failed. Verify this is a valid git repository."
  exit 1
fi

PINNED_DATE=$(cat "$META_FILE" | jq -r '.commit_date')

echo "Docs pinned to: $PINNED_HASH ($PINNED_DATE)"
echo "Current HEAD:   $CURRENT_HASH"

if [ "$PINNED_HASH" = "$CURRENT_HASH" ]; then
  echo "Docs are up to date. Nothing to refresh."
  exit 0
fi

# Verify pinned commit exists
COMMIT_COUNT=$(git rev-list --count "$PINNED_HASH".."$CURRENT_HASH" 2>/dev/null || echo "unknown")
if [ "$COMMIT_COUNT" = "unknown" ]; then
  echo "ERROR: Pinned commit $PINNED_HASH not found. It may have been rebased or force-pushed."
  echo "Falling back to full refresh via /stackshift.reverse-engineer."
  exit 1
fi

echo "Commits since last generation: $COMMIT_COUNT"
```

If any git command fails (non-zero exit), report the error to the user. Common causes: shallow clone (suggest `git fetch --unshallow`), corrupted repo (suggest `git fsck`), or missing commit (suggest full refresh).

Log: "Step 1 complete: $COMMIT_COUNT commits to analyze."

### Step 2: Get Changed Files and Commit Summary

Log: "Step 2: Gathering changed files..."

```bash
# Get list of changed files with change type
git diff --name-status "$PINNED_HASH"..HEAD 2>/dev/null
if [ $? -ne 0 ]; then
  echo "ERROR: git diff failed. Check repository integrity."
  exit 1
fi

# Get commit log summary (for context)
git log --oneline "$PINNED_HASH"..HEAD

# Get a statistical summary
git diff --stat "$PINNED_HASH"..HEAD
```

Present the change summary to the user:
```
Docs generated at commit abc1234 (2025-12-15)
Current HEAD: def4567 (2026-02-12)
42 commits, 156 files changed:
  src/api/        - 12 files (endpoints, middleware)
  src/models/     - 3 files (schema changes)
  tests/          - 15 new test files
Estimated refresh time: ~5 minutes
```

If mode is `full` (user-requested or auto-detected), skip to the Full Refresh section below.

Log: "Step 2 complete: [N] files changed across [M] directories."

### Step 3: Map Changes to Affected Docs

Log: "Step 3: Mapping changed files to docs..."

Categorize each changed file by which documentation file(s) it affects:

| Changed File Pattern | Affected Doc(s) |
|---|---|
| `src/api/**`, `routes/**`, `controllers/**` | functional-specification.md, integration-points.md, data-architecture.md |
| `src/models/**`, `schema/**`, `prisma/**`, `migrations/**` | data-architecture.md |
| `src/services/**`, `src/lib/**`, `src/utils/**` | functional-specification.md |
| `package.json`, `go.mod`, `requirements.txt` | decision-rationale.md, configuration-reference.md |
| `.env*`, `config/**`, `*.config.*` | configuration-reference.md |
| `docker*`, `terraform/**`, `k8s/**`, `.github/**` | operations-guide.md |
| `tests/**`, `__tests__/**`, `*.test.*`, `*.spec.*` | test-documentation.md |
| `src/components/**`, `src/pages/**`, `styles/**` | visual-design-system.md |
| `README*`, `CHANGELOG*`, `docs/**` | business-context.md |
| Infrastructure/monitoring files | observability-requirements.md |
| Any tech stack changes | decision-rationale.md |
| External service integrations | integration-points.md |

Skip files that do not map to any doc (e.g., `.gitignore` changes).

Output a refresh plan showing which docs need updates and which are unchanged.

Log: "Step 3 complete: [N] docs need updates, [M] docs unchanged."

### Step 4: Analyze Changes and Update Docs

Log: "Step 4: Updating docs..."

For each affected doc, launch a separate Task agent with `subagent_type=Explore` (or `stackshift:stackshift-code-analyzer:AGENT`). Each agent receives the doc path and its mapped changed files. Agents may run in parallel.

Each agent must:

1. Read the current doc to understand its structure
2. Read the changed files that map to this doc
3. Read the git diff for those files: `git diff "$PINNED_HASH"..HEAD -- "$file"`
4. Determine updates needed:
   - New sections to add (e.g., new API endpoint = new FR)
   - Existing sections to modify (e.g., schema change = update data model)
   - Sections to remove (e.g., deleted feature = remove FR)
   - No change needed (e.g., refactor that does not change behavior)

Update strategy per change type:

| Change Type | Action |
|---|---|
| **New file** (Added) | Add new section/entry to the relevant doc |
| **Modified file** | Read diff, update affected sections, preserve unchanged content |
| **Deleted file** | Mark related sections as removed or deprecated |
| **Renamed file** | Update file paths in the doc |
| **New dependency** | Add to decision-rationale.md and/or integration-points.md |
| **Config change** | Update configuration-reference.md |
| **New test** | Update test-documentation.md coverage |

Surgical updates only -- rewriting entire docs risks losing manually-added content and wastes tokens. Use the Edit tool to modify specific sections.

Always quote file paths in git commands to handle spaces and special characters.

Track the result of each doc update: record which docs succeeded and which failed.

Log after each doc: "Updated [doc-name] ([N] sections changed)" or "FAILED to update [doc-name]: [reason]"

### Step 4b: Verify Updates

Before proceeding, verify that all targeted docs were successfully updated:

1. For each doc that was updated, read the modified sections and confirm the changes match the diff analysis.
2. If any doc update failed or a doc was inadvertently overwritten, restore it from git (`git checkout HEAD -- "path/to/doc"`) and retry with the Edit tool.
3. Build two lists: `successful_docs` (docs that were correctly updated) and `failed_docs` (docs that could not be updated).

If any docs remain in `failed_docs` after retry, keep the old commit hash for those docs in the metadata (Step 5) and note the failures in the summary (Step 7).

Log: "Step 4b complete: [N] docs verified, [M] failures."

### Step 5: Update Metadata

Step 5 must complete before Step 6 (Step 6 uses values computed here).

Log: "Step 5: Updating metadata..."

```bash
NEW_HASH=$(git rev-parse HEAD)
NEW_DATE=$(git log -1 --format=%ci)
REFRESHED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
```

Update `docs/reverse-engineering/.stackshift-docs-meta.json`:
- Set `commit_hash` to new HEAD
- Set `commit_date` to new date
- For each successfully updated doc, set its `last_updated` to now and `commit_hash` to new HEAD
- For unchanged docs, keep their original ti