refresh-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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 new commit hash

基于Git变更增量更新逆向工程文档 — 无需全量生成

**预计耗时：**2-15分钟（取决于变更规模） **前置条件：**已存在带.stackshift-docs-meta.json的逆向工程文档 **输出：**docs/reverse-engineering/目录下的更新后文档，附带新的提交哈希

When to Use This Skill

何时使用该技能

Use this skill when:

Reverse-engineering docs already exist from a previous run
Code has changed since docs were generated (new commits)
You want to keep docs up to date without full regeneration
Cost/time matters — only analyze what changed

Trigger Phrases:

"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?"

在以下场景使用本技能：

已通过之前的运行生成了逆向工程文档
自文档生成后代码发生了变更（有新的提交）
希望无需全量生成即可保持文档最新
在意成本/时间 — 仅分析变更的内容

触发语：

"更新逆向工程文档"
"刷新文档"
"同步文档与最新代码"
"自文档生成后有哪些变更？"
"文档是否已过时？"

What This Skill Does

本技能的功能

Previous Docs (commit abc123)           Latest Code (commit def456)
┌─────────────────────────┐            ┌─────────────────────────┐
│ 11 reverse-eng docs     │            │ New commits since abc123│
│ .stackshift-docs-meta   │──── diff ──│ Changed files list      │
└─────────────────────────┘            └─────────────────────────┘
                                                │
                                       Analyze only changes
                                                │
                                                ▼
                                       Updated docs + new hash

Reads the pinned commit hash from
```
.stackshift-docs-meta.json
```
Runs
```
git diff
```
between that hash and HEAD
Categorizes changed files by which docs they affect
Analyzes only the changed code
Surgically updates affected sections in the relevant docs
Updates the commit hash in metadata

Previous Docs (commit abc123)           Latest Code (commit def456)
┌─────────────────────────┐            ┌─────────────────────────┐
│ 11 reverse-eng docs     │            │ New commits since abc123│
│ .stackshift-docs-meta   │──── diff ──│ Changed files list      │
└─────────────────────────┘            └─────────────────────────┘
                                                │
                                       Analyze only changes
                                                │
                                                ▼
                                       Updated docs + new hash

从.stackshift-docs-meta.json读取固定的提交哈希
在该哈希与HEAD之间运行
```
git diff
```
根据变更文件对应的文档进行分类
仅分析变更的代码
精准更新相关文档中的受影响章节
更新元数据中的提交哈希

Process

流程

Step 1: Read Metadata and Assess Changes

步骤1：读取元数据并评估变更

bash

undefined

bash

undefined

Read the pinned commit hash

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

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

Count commits since docs were generated

COMMIT_COUNT=$(git rev-list --count "$PINNED_HASH".."$CURRENT_HASH" 2>/dev/null || echo "unknown") echo "Commits since last generation: $COMMIT_COUNT"

undefined

COMMIT_COUNT=$(git rev-list --count "$PINNED_HASH".."$CURRENT_HASH" 2>/dev/null || echo "unknown") echo "Commits since last generation: $COMMIT_COUNT"

undefined

Step 2: Get Changed Files and Commit Summary

步骤2：获取变更文件与提交摘要

bash

undefined

bash

undefined

Get list of changed files with change type

git diff --name-status "$PINNED_HASH"..HEAD

Get commit log summary (for context)

git log --oneline "$PINNED_HASH"..HEAD

Get a statistical summary

git diff --stat "$PINNED_HASH"..HEAD


**Present to user:**

Docs were 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 (User, Product schemas) src/services/ - 8 files (business logic) package.json - dependency updates .env.example - new env vars docker-compose - infrastructure changes tests/ - 15 new test files

Estimated refresh time: ~5 minutes

undefined

git diff --stat "$PINNED_HASH"..HEAD


**展示给用户：**

Docs were generated at commit abc1234 (2025-12-15) Current HEAD: def4567 (2026-02-12)

Estimated refresh time: ~5 minutes

undefined

Step 3: Map Changes to Affected Docs

步骤3：将变更映射到受影响的文档

Categorize each changed file by which reverse-engineering doc(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

Files that don't map to any doc (e.g.,

.gitignore

changes) can be skipped.

Output a refresh plan:

Docs to update:
  functional-specification.md  - 8 changed files affect this doc
  data-architecture.md         - 3 changed files (schema changes)
  configuration-reference.md   - 2 changed files (new env vars)
  test-documentation.md        - 15 new test files

Docs unchanged:
  visual-design-system.md      - no UI changes detected
  observability-requirements.md - no monitoring changes
  business-context.md          - no business context changes
  decision-rationale.md        - no tech stack changes
  operations-guide.md          - no infra changes
  integration-points.md        - no integration changes
  technical-debt-analysis.md   - no debt-relevant changes

将每个变更文件按其影响的逆向工程文档进行分类：

变更文件模式	受影响的文档
`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
基础设施/监控文件	observability-requirements.md
任何技术栈变更	decision-rationale.md
外部服务集成	integration-points.md

不映射到任何文档的文件（例如.gitignore变更）可跳过。

输出刷新计划：

Docs to update:
  functional-specification.md  - 8 changed files affect this doc
  data-architecture.md         - 3 changed files (schema changes)
  configuration-reference.md   - 2 changed files (new env vars)
  test-documentation.md        - 15 new test files

Docs unchanged:
  visual-design-system.md      - no UI changes detected
  observability-requirements.md - no monitoring changes
  business-context.md          - no business context changes
  decision-rationale.md        - no tech stack changes
  operations-guide.md          - no infra changes
  integration-points.md        - no integration changes
  technical-debt-analysis.md   - no debt-relevant changes

Step 4: Analyze Changes and Update Docs

步骤4：分析变更并更新文档

For each affected doc, use the Task tool with

subagent_type=Explore

(or

stackshift:code-analyzer

) to:

Read the current doc to understand its structure and content
Read the changed files that map to this doc
Read the git diff for those files to understand what specifically changed
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 doesn't change behavior)

Update strategy per change type:

Change Type	Update Approach
New file (Added)	Add new section/entry to relevant doc
Modified file	Read diff, update affected sections, preserve unchanged
Deleted file	Mark related sections as removed or deprecated
Renamed file	Update file paths in brownfield docs
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

Important: Surgical updates only. Do NOT rewrite entire docs. Edit specific sections using the Edit tool to preserve unchanged content.

对于每个受影响的文档，使用Task工具并设置

subagent_type=Explore

（或

stackshift:code-analyzer

）来执行以下操作：

读取当前文档以理解其结构与内容
读取变更의文件中与该文档相关的部分
读取这些文件的git diff以明确具体变更内容
确定所需的更新：
- 需要添加的新章节（例如：新API端点 → 新增功能需求）
- 需要修改的现有章节（例如： schema变更 → 更新数据模型）
- 需要移除的章节（例如：删除功能 → 移除对应功能需求）
- 无需变更（例如：不影响功能的重构）

按变更类型的更新策略：

变更类型	更新方式
新增文件	在相关文档中添加新章节/条目
修改文件	读取diff，更新受影响的章节，保留未变更内容
删除文件	将相关章节标记为已移除或已弃用
重命名文件	更新遗留文档中的文件路径
新增依赖	添加到decision-rationale.md和/或integration-points.md
配置变更	更新configuration-reference.md
新增测试	更新test-documentation.md的覆盖范围

重要提示：仅进行精准更新。请勿重写整个文档。使用Edit工具编辑特定章节，以保留未变更的内容。

Step 5: Update Metadata

步骤5：更新元数据

After all docs are updated, update the metadata file:

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 updated doc, set its
```
generated_at
```
to now and
```
commit_hash
```
to new HEAD
For unchanged docs, keep their original timestamps
Add a
```
refresh_history
```
array tracking each refresh:

json

{
  "commit_hash": "<NEW_HASH>",
  "commit_date": "<NEW_DATE>",
  "generated_at": "<original generation date>",
  "last_refreshed_at": "<REFRESHED_AT>",
  "doc_count": 11,
  "route": "brownfield",
  "refresh_history": [
    {
      "from_commit": "<OLD_HASH>",
      "to_commit": "<NEW_HASH>",
      "refreshed_at": "<REFRESHED_AT>",
      "commits_analyzed": 42,
      "files_changed": 156,
      "docs_updated": ["functional-specification.md", "data-architecture.md", "configuration-reference.md", "test-documentation.md"],
      "docs_unchanged": ["visual-design-system.md", "observability-requirements.md", "..."]
    }
  ],
  "docs": {
    "functional-specification.md": { "generated_at": "<original>", "last_updated": "<REFRESHED_AT>", "commit_hash": "<NEW_HASH>" },
    "data-architecture.md": { "generated_at": "<original>", "last_updated": "<REFRESHED_AT>", "commit_hash": "<NEW_HASH>" },
    "configuration-reference.md": { "generated_at": "<original>", "last_updated": "<REFRESHED_AT>", "commit_hash": "<NEW_HASH>" },
    "test-documentation.md": { "generated_at": "<original>", "last_updated": "<REFRESHED_AT>", "commit_hash": "<NEW_HASH>" },
    "visual-design-system.md": { "generated_at": "<original>", "last_updated": "<original>", "commit_hash": "<OLD_HASH>" },
    "...": "unchanged docs keep old timestamps"
  }
}

在所有文档更新完成后，更新元数据文件：

bash

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

更新

docs/reverse-engineering/.stackshift-docs-meta.json

：

将
```
commit_hash
```
设置为新的HEAD
将
```
commit_date
```
设置为新的日期
对于每个更新后的文档，将其
```
generated_at
```
设置为当前时间，
```
commit_hash
```
设置为新的HEAD
对于未变更的文档，保留其原始时间戳
添加
```
refresh_history
```
数组以跟踪每次刷新：

json

{
  "commit_hash": "<NEW_HASH>",
  "commit_date": "<NEW_DATE>",
  "generated_at": "<original generation date>",
  "last_refreshed_at": "<REFRESHED_AT>",
  "doc_count": 11,
  "route": "brownfield",
  "refresh_history": [
    {
      "from_commit": "<OLD_HASH>",
      "to_commit": "<NEW_HASH>",
      "refreshed_at": "<REFRESHED_AT>",
      "commits_analyzed": 42,
      "files_changed": 156,
      "docs_updated": ["functional-specification.md", "data-architecture.md", "configuration-reference.md", "test-documentation.md"],
      "docs_unchanged": ["visual-design-system.md", "observability-requirements.md", "..."]
    }
  ],
  "docs": {
    "functional-specification.md": { "generated_at": "<original>", "last_updated": "<REFRESHED_AT>", "commit_hash": "<NEW_HASH>" },
    "data-architecture.md": { "generated_at": "<original>", "last_updated": "<REFRESHED_AT>", "commit_hash": "<NEW_HASH>" },
    "configuration-reference.md": { "generated_at": "<original>", "last_updated": "<REFRESHED_AT>", "commit_hash": "<NEW_HASH>" },
    "test-documentation.md": { "generated_at": "<original>", "last_updated": "<REFRESHED_AT>", "commit_hash": "<NEW_HASH>" },
    "visual-design-system.md": { "generated_at": "<original>", "last_updated": "<original>", "commit_hash": "<OLD_HASH>" },
    "...": "unchanged docs keep old timestamps"
  }
}

Step 6: Update Doc Headers

步骤6：更新文档头部

For each updated doc, update the metadata header line:

markdown

> **Generated by StackShift** | Commit: `<new-short-hash>` | Updated: `<REFRESHED_AT>` | Originally generated: `<original-date>`

对于每个更新后的文档，更新元数据头部行：

markdown

> **Generated by StackShift** | Commit: `<new-short-hash>` | Updated: `<REFRESHED_AT>` | Originally generated: `<original-date>`

Step 7: Present Summary

步骤7：展示摘要

Docs Refresh Complete
═════════════════════

Analyzed: 42 commits (abc1234 → def4567)
Changed files: 156
Time: 4 minutes

Updated docs (4):
  functional-specification.md
    + Added FR-008: Bulk export feature
    ~ Updated FR-003: Modified user registration flow
    - Removed FR-005: Legacy import (deleted)

  data-architecture.md
    + Added Product.variants field
    ~ Updated User model (new preferences column)

  configuration-reference.md
    + Added EXPORT_BATCH_SIZE env var
    + Added REDIS_CLUSTER_URL env var

  test-documentation.md
    ~ Coverage updated: 67% → 74%
    + 15 new test files documented

Unchanged docs (7):
  visual-design-system.md, observability-requirements.md,
  business-context.md, decision-rationale.md, operations-guide.md,
  integration-points.md, technical-debt-analysis.md

Next refresh: Run /stackshift.refresh-docs again after more commits.

Docs Refresh Complete
═════════════════════

Analyzed: 42 commits (abc1234 → def4567)
Changed files: 156
Time: 4 minutes

Updated docs (4):
  functional-specification.md
    + Added FR-008: Bulk export feature
    ~ Updated FR-003: Modified user registration flow
    - Removed FR-005: Legacy import (deleted)

  data-architecture.md
    + Added Product.variants field
    ~ Updated User model (new preferences column)

  configuration-reference.md
    + Added EXPORT_BATCH_SIZE env var
    + Added REDIS_CLUSTER_URL env var

  test-documentation.md
    ~ Coverage updated: 67% → 74%
    + 15 new test files documented

Unchanged docs (7):
  visual-design-system.md, observability-requirements.md,
  business-context.md, decision-rationale.md, operations-guide.md,
  integration-points.md, technical-debt-analysis.md

Next refresh: Run /stackshift.refresh-docs again after more commits.

Modes

模式

Default: Smart Refresh

默认：智能刷新

Only updates docs affected by changes
Preserves unchanged sections
Fast and cost-effective

仅更新受变更影响的文档
保留未变更的章节
快速且成本低

Full Refresh (override)

全量刷新（覆盖默认）

If the user says "do a full refresh" or changes are too extensive (100+ files, major refactor):

Regenerate all 11 docs from scratch using
```
/stackshift.reverse-engineer
```
Equivalent to a full Gear 2 run
Use when: major refactors, framework migrations, or when incremental updates would miss systemic changes

Auto-detect when full refresh is recommended:

More than 60% of source files changed
Package.json/go.mod major version bumps
New top-level directories added
Framework migration detected (e.g., Express → Fastify)

Large change detected: 78% of source files modified.
A full refresh is recommended over incremental update.

A) Full refresh (regenerate all docs, ~30 min)
B) Incremental anyway (faster but may miss systemic changes)

如果用户说“执行全量刷新”或变更范围过大（100+文件、重大重构）：

使用
```
/stackshift.reverse-engineer
```
从头重新生成所有11份文档
等同于完整的Gear 2运行
使用场景：重大重构、框架迁移、或增量更新可能遗漏系统性变更时

自动检测是否推荐全量刷新：

超过60%的源文件发生变更
package.json/go.mod主版本升级
新增顶级目录
检测到框架迁移（例如：Express → Fastify）

Large change detected: 78% of source files modified.
A full refresh is recommended over incremental update.

A) Full refresh (regenerate all docs, ~30 min)
B) Incremental anyway (faster but may miss systemic changes)

Edge Cases

边缘情况

Docs exist but no metadata file

文档存在但无元数据文件

Legacy docs from before commit tracking. Offer two options:

Run
```
/stackshift.reverse-engineer
```
to regenerate with metadata
Create metadata file pinned to current HEAD (treats current docs as up-to-date)

属于提交跟踪之前的遗留文档。提供两个选项：

运行
```
/stackshift.reverse-engineer
```
重新生成文档并附带元数据
创建固定到当前HEAD的元数据文件（将当前文档视为已更新）

Pinned commit no longer exists

固定的提交已不存在

The commit was rebased or force-pushed away. Fall back to full refresh.

该提交已被变基或强制推送移除。 fallback到全量刷新。

No git repository

非Git仓库

Not a git repo. Cannot do incremental updates. Guide user to full regeneration.

不是Git仓库，无法执行增量更新。引导用户进行全量生成。

Merge commits

合并提交

When the diff spans merge commits, use

git diff

(not

git log -p

) to get the net effect rather than per-commit changes.

当diff包含合并提交时，使用

git diff

（而非

git log -p

）来获取净变更效果，而非每个提交的变更。

Integration

集成

With Cruise Control

与Cruise Control集成

Cruise control can optionally run refresh-docs instead of full reverse-engineer if docs already exist:

Existing docs detected (pinned to abc1234, 15 commits behind).
A) Refresh docs incrementally (~5 min)
B) Full regeneration (~30 min)

如果已存在文档，Cruise Control可选择运行refresh-docs而非全量逆向工程：

Existing docs detected (pinned to abc1234, 15 commits behind).
A) Refresh docs incrementally (~5 min)
B) Full regeneration (~30 min)

With Batch Processing

与批量处理集成

Batch mode can run refresh-docs on repos that already have docs, saving significant time when re-processing a large monorepo.

批量模式可在已有文档的仓库上运行refresh-docs，在重新处理大型单体仓库时节省大量时间。

With CI/CD

与CI/CD集成

Can be run in CI to keep docs updated on every merge to main:

yaml

- name: Refresh StackShift docs
  run: |
    # Check if docs need refresh
    if [ -f "docs/reverse-engineering/.stackshift-docs-meta.json" ]; then
      echo "Refreshing docs..."
      # Trigger /stackshift.refresh-docs
    fi

可在CI中运行，以在每次合并到main分支时保持文档更新：

yaml

- name: Refresh StackShift docs
  run: |
    # Check if docs need refresh
    if [ -f "docs/reverse-engineering/.stackshift-docs-meta.json" ]; then
      echo "Refreshing docs..."
      # Trigger /stackshift.refresh-docs
    fi

Success Criteria

成功标准

✅ Changes since pinned commit identified and categorized
✅ Only affected docs updated (unchanged docs preserved)
✅ Metadata file updated with new commit hash
✅ Refresh history logged
✅ Doc headers updated with new timestamps
✅ Summary shows what was added/modified/removed per doc

✅ 已识别并分类自固定提交以来的变更
✅ 仅更新受影响的文档（保留未变更的文档）
✅ 元数据文件已更新为新的提交哈希
✅ 已记录刷新历史
✅ 文档头部已更新为新的时间戳
✅ 摘要展示了每份文档的新增/修改/移除内容

Technical Notes

技术说明

Use
```
git diff --name-status
```
for file-level change detection (fast)
Use
```
git diff <hash>..HEAD -- <file>
```
for content-level analysis of specific files
Parallelize: Read changed files for different docs concurrently using Task agents
For large diffs (500+ files), batch the analysis into groups of 50 files
Preserve doc structure — use Edit tool for surgical updates, not Write for full rewrites
The metadata JSON should be committed to git so team members share the same pinned hash

使用
```
git diff --name-status
```
进行文件级变更检测（速度快）
使用
```
git diff <hash>..HEAD -- <file>
```
对特定文件进行内容级分析
并行处理：使用Task代理同时读取不同文档对应的变更文件
对于大型diff（500+文件），将分析分批为每组50个文件
保留文档结构 — 使用Edit工具进行精准更新，而非使用Write工具重写全文
元数据JSON应提交到Git，以便团队成员共享相同的固定哈希