scrolls-update

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Updating docs/.scrolls/

更新docs/.scrolls/

docs/.scrolls/

only stays useful if it reflects reality. This skill applies the update rules

STARTER.md

already defines for each file — it does not invent new conventions. The point isn't to touch every file every time; it's to touch exactly the files that something actually happened to, using the update discipline that file's own convention calls for (overwrite vs. append vs. add/remove in lockstep).

docs/.scrolls/

只有反映实际情况才有用。此技能遵循

STARTER.md

已为每个文件定义的更新规则——不会创建新的约定。目标并非每次都修改所有文件，而是仅修改实际发生变化的文件，并遵循该文件自身约定的更新规则（覆盖、追加或同步添加/删除）。

Cross-platform

跨平台支持

The one bundled script (step 3) ships in two forms:

session_diff.sh

(bash — macOS, Linux, or Windows with Git Bash/WSL) and

session_diff.ps1

(PowerShell 7+ — Windows, or macOS/Linux with

pwsh

installed). Everything else in this skill — the flags,

BASE_DIR

resolution, locating the scrolls folder — is plain prose you follow directly; it only ever invokes

git

, which behaves identically regardless of which shell is running it, so none of that needs a shell-specific variant. Pick the script by what's actually available: try

bash --version

; if that succeeds, use the

.sh

script; otherwise use the

.ps1

script via

pwsh

(preferred — install from https://aka.ms/powershell if missing) or, only if

pwsh

genuinely isn't available, the built-in Windows PowerShell

powershell.exe

(untested against that older version;

pwsh

is what this was written and verified against).

附带的单个脚本（步骤3）有两种形式：

session_diff.sh

（bash——适用于macOS、Linux或安装了Git Bash/WSL的Windows）和

session_diff.ps1

（PowerShell 7+——适用于Windows，或安装了

pwsh

的macOS/Linux）。此技能中的其他所有内容——标志、

BASE_DIR

解析、定位卷轴文件夹——都是直接遵循的纯文本说明；它只会调用

git

，而

git

在任何shell中运行的行为都相同，因此无需针对不同shell提供变体。根据实际可用环境选择脚本：尝试运行

bash --version

；如果成功，使用

.sh

脚本；否则通过

pwsh

powershell.exe

（未针对该旧版本测试；

pwsh

是编写和验证此脚本所使用的环境）。

Options

选项

Read the invocation text for these, in any order — there's no real argv parser here, so pull them out of the plain text yourself:

-p <path>
/
--path=<path>
/
--path <path>
— a custom docs folder to look in, relative to the current working directory unless given as an absolute path.
-t
/
--reporoot
— look under the git repository's top level (
```
$(git rev-parse --show-toplevel)
```
) regardless of which subdirectory you actually invoked this from. Fails with a clear message if the current directory isn't inside a git repository.
-l
/
--local
— look explicitly in the current working directory. This is what happens by default anyway when none of
```
-p
```
/
```
-t
```
/
```
-l
```
are given — the flag exists to say so on purpose, e.g. to skip the mismatch check below.
-r
/
--recurse
— if the scrolls folder isn't at the obvious exact location (
```
BASE_DIR/docs/.scrolls
```
or
```
BASE_DIR/docs/scrolls
```
), search recursively under
```
BASE_DIR
```
for one instead of giving up. Off by default — matches the usual meaning of
```
-r
```
on tools like
```
grep
```
/
```
cp
```
/
```
rm
```
.

There's no

-u

--unhide

option here — this skill locates whichever scrolls folder already exists rather than choosing between them (see step 1).

-p

-t

, and

-l

are three different ways to answer the same question ("where's the docs folder?") — pass at most one; if more than one is given, ask which was meant.

-r

is independent and combines freely with any of them (or with none).

阅读调用文本中的这些选项，顺序不限——此处没有真正的argv解析器，因此请自行从纯文本中提取：

-p <path>
/
--path=<path>
/
--path <path>
——指定自定义docs文件夹路径，除非给定绝对路径，否则相对于当前工作目录。
-t
/
--reporoot
——在Git仓库的顶层目录（
```
$(git rev-parse --show-toplevel)
```
）下查找，无论实际从哪个子目录调用。如果当前目录不在Git仓库内，会给出明确的失败提示。
-l
/
--local
——明确在当前工作目录查找。当未指定
```
-p
```
/
```
-t
```
/
```
-l
```
时，默认就是此行为——该标志用于明确指定此操作，例如跳过下文的不匹配检查。
-r
/
--recurse
——如果卷轴文件夹不在明显的精确位置（
```
BASE_DIR/docs/.scrolls
```
或
```
BASE_DIR/docs/scrolls
```
），则在
```
BASE_DIR
```
下递归搜索，而非直接放弃。默认关闭——与
```
grep
```
/
```
cp
```
/
```
rm
```
等工具中
```
-r
```
的常见含义一致。

此处没有

-u

--unhide

选项——此技能会定位已存在的卷轴文件夹，而非在它们之间选择（见步骤1）。

-p

、

-t

和

-l

是回答同一问题（“docs文件夹在哪里？”）的三种不同方式——最多传递一个；如果指定多个，请询问用户的意图。

-r

是独立选项，可与其中任意一个（或不与任何一个）组合使用。

Steps

步骤

1. Resolve BASE_DIR, then locate the scrolls, trying both names

1. 解析BASE_DIR，然后定位卷轴文件夹，尝试两种命名方式

Compute

BASE_DIR

-t
/
--reporoot
given:
```
BASE_DIR = $(git rev-parse --show-toplevel)
```
. If that fails (not inside a git repository), stop and tell the user — suggest
```
--path
```
instead.
-l
/
--local
given:
```
BASE_DIR = $(pwd)
```
.
Nothing given (the common case):
```
BASE_DIR = $(pwd)
```
. But first, if the current directory is inside a git repository, run
```
git rev-parse --show-toplevel
```
and compare it to
```
$(pwd)
```
. If they're the same, or this isn't a git repo, proceed with cwd as usual. If they differ, mention it before searching — running from here will only look under
```
$(pwd)/docs
```
, and a scrolls folder that lives at the repository root (
```
<repo-root>
```
) instead would be missed entirely (not just skipped — it'll look like the project was never set up). Ask if that's intended, defaulting to proceeding with cwd (this skill's documented default) if there's no strong preference.

Then let

DOCS_BASE

be the

--path

value if

-p

was given, else

${BASE_DIR}/docs

. The scrolls folder under it may be named either

.scrolls

(hidden, the default from

/scrolls-setup

) or

scrolls

(after

/scrolls-unhide

, or

--unhide

at setup time) — check for

DOCS_BASE/.scrolls

first, then

DOCS_BASE/scrolls

. Whichever exists is

SCROLLS_PATH

for the rest of this skill.

If neither exists at that exact spot:

-r
/
--recurse
was given: search recursively under
```
BASE_DIR
```
instead — a bounded number of levels deep, pruning the same heavy/vendor directories
```
/scrolls-hide
```
/
```
/scrolls-unhide
```
prune (
```
node_modules
```
,
```
.git
```
,
```
vendor
```
,
```
dist
```
,
```
build
```
,
```
.venv
```
,
```
venv
```
,
```
__pycache__
```
,
```
target
```
,
```
.next
```
,
```
.cache
```
), for a directory named
```
.scrolls
```
or
```
scrolls
```
containing a
```
STARTER.md
```
. If exactly one turns up, that's
```
SCROLLS_PATH
```
. If more than one turns up (a monorepo with several independent scrolls setups under this
```
BASE_DIR
```
), list them and ask the user which one this session's update is actually about — don't guess, and don't update more than one, since a session's narrative belongs to a specific project, not every project it happens to be nested near.
-r
wasn't given, or the recursive search above also found nothing: don't create one here. Tell the user this project (or this path) hasn't been set up yet and point them at
```
/scrolls-setup
```
— and if you resolved
```
BASE_DIR
```
to cwd (by default or
```
-l
```
) rather than the repo root, mention
```
-t
```
/
```
--reporoot
```
as something to try, and mention
```
-r
```
/
```
--recurse
```
if you haven't already used it, in case the scrolls live somewhere other than the exact expected spot.

If somehow both

.scrolls

and

scrolls

exist at the exact

DOCS_BASE

, stop and ask the user which one is current — that's an inconsistent state this skill shouldn't silently paper over.

计算

BASE_DIR

：

指定了
-t
/
--reporoot
：
```
BASE_DIR = $(git rev-parse --show-toplevel)
```
。如果失败（不在Git仓库内），停止操作并告知用户——建议使用
```
--path
```
替代。
指定了
-l
/
--local
：
```
BASE_DIR = $(pwd)
```
。
未指定任何选项（常见情况）：
```
BASE_DIR = $(pwd)
```
。但首先，如果当前目录在Git仓库内，运行
```
git rev-parse --show-toplevel
```
并与
```
$(pwd)
```
比较。如果两者相同，或者当前不在Git仓库中，则照常使用当前工作目录。如果两者不同，在搜索前告知用户——从当前目录运行只会在
```
$(pwd)/docs
```
下查找，而位于仓库根目录（
```
<repo-root>
```
）的卷轴文件夹会被完全遗漏（不仅是跳过——看起来像是项目从未设置过）。询问用户是否有意如此，如果没有明确偏好，默认使用当前工作目录（此技能文档中记录的默认行为）。

然后，如果指定了

-p

，则

DOCS_BASE

为

--path

的值，否则为

${BASE_DIR}/docs

。其下的卷轴文件夹可能命名为

.scrolls

（隐藏，/scrolls-setup的默认名称）或

scrolls

（在/scrolls-unhide之后，或设置时使用

--unhide

）——先检查

DOCS_BASE/.scrolls

，再检查

DOCS_BASE/scrolls

。存在的那个即为后续步骤中的

SCROLLS_PATH

。

如果该精确位置不存在任何一个：

指定了
-r
/
--recurse
：改为在
```
BASE_DIR
```
下递归搜索——搜索有限的深度，排除与
```
/scrolls-hide
```
/
```
/scrolls-unhide
```
相同的大型/供应商目录（
```
node_modules
```
、
```
.git
```
、
```
vendor
```
、
```
dist
```
、
```
build
```
、
```
.venv
```
、
```
venv
```
、
```
__pycache__
```
、
```
target
```
、
```
.next
```
、
```
.cache
```
），查找名为
```
.scrolls
```
或
```
scrolls
```
且包含
```
STARTER.md
```
的目录。如果恰好找到一个，那就是
```
SCROLLS_PATH
```
。如果找到多个（此
```
BASE_DIR
```
下有多个独立卷轴设置的单体仓库），列出它们并询问用户本次会话更新针对的是哪一个——不要猜测，也不要更新多个，因为会话的记录属于特定项目，而非它所在的所有嵌套项目。
未指定
-r
，或上述递归搜索也未找到任何内容：不要在此创建。告知用户此项目（或此路径）尚未设置，并引导其使用/scrolls-setup——如果
```
BASE_DIR
```
解析为当前工作目录（默认或
```
-l
```
）而非仓库根目录，建议尝试
```
-t
```
/
```
--reporoot
```
，如果尚未使用
```
-r
```
/
```
--recurse
```
，也建议尝试，因为卷轴文件夹可能位于非预期的位置。

如果

DOCS_BASE

下同时存在

.scrolls

和

scrolls

，停止操作并询问用户哪一个是当前在用的——这种不一致状态不应被此技能无声地掩盖。

2. Read STARTER.md as the authoritative map

2. 读取STARTER.md作为权威指南

Don't assume the minimal six-file set from

/scrolls-setup

is still the whole story —

STARTER.md

says explicitly that projects grow additional scrolls over time (architecture decisions, security reviews, subsystem deep-dives), each listed with its own read/update rule. Read the current

STARTER.md

in full and use its numbered list and "When to update" section as the source of truth for what files exist and how each one wants to be updated. If a file's update convention differs from the generic rules below (e.g. an append-only dated log that must never be edited in place, like this repo's own

SECURITY_ANALYSIS.md

), follow that file's specific convention over the generic one.

不要假设/scrolls-setup中的最小六文件集合仍然是全部内容——

STARTER.md

明确说明项目会随时间增加更多卷轴文件（架构决策、安全审查、子系统深入分析），每个文件都列出了自己的读取/更新规则。完整读取当前的

STARTER.md

，并以其编号列表和“何时更新”部分作为文件存在情况及每个文件更新方式的唯一依据。如果某个文件的更新约定与以下通用规则不同（例如，像本仓库自身的

SECURITY_ANALYSIS.md

那样，是仅可追加的日期日志，绝不能就地编辑），则遵循该文件的特定约定而非通用规则。

3. Establish what actually happened this session

3. 确定本次会话实际发生的内容

Conversation context is the primary source — you were there. But don't rely on it alone, especially if context has been compacted, the session was resumed, or you're being asked to update scrolls for work that happened before this conversation started. Run the bundled script to cross-check against git — pick whichever of the two ships in

<skill-dir>/scripts/

matches the current environment (see "Cross-platform" below):

bash <skill-dir>/scripts/session_diff.sh SCROLLS_PATH
pwsh <skill-dir>/scripts/session_diff.ps1 -ScrollsDir SCROLLS_PATH

It shows uncommitted changes, commits since

docs/.scrolls/

was last touched, and a stat summary of what files changed — enough to catch things conversation memory missed, without dumping full diffs into context. Pull specific

git diff

git log -p

slices yourself if you need more detail on a particular change.

对话上下文是主要来源——你全程参与了会话。但不要仅依赖上下文，尤其是在上下文已压缩、会话已恢复，或者被要求更新会话开始前完成的工作的卷轴文件时。运行附带的脚本与git交叉验证——选择

<skill-dir>/scripts/

中与当前环境匹配的脚本（见下文“跨平台支持”）：

bash <skill-dir>/scripts/session_diff.sh SCROLLS_PATH
pwsh <skill-dir>/scripts/session_diff.ps1 -ScrollsDir SCROLLS_PATH

它会显示未提交的更改、自上次修改

docs/.scrolls/

以来的提交，以及文件更改的统计摘要——足以捕捉对话记忆遗漏的内容，而不会将完整差异转储到上下文中。如果需要特定更改的更多细节，可自行提取

git diff

git log -p

的具体内容。

4. Update each file that needs it, following its own rule

4. 更新每个需要修改的文件，遵循其自身规则

The core six's generic rules (from

STARTER.md

HANDOFF.md
— overwrite, don't append. It's a snapshot: current state, what just happened, known issues/open threads. If nothing meaningfully changed this session, it's fine to leave it as-is rather than padding it with a no-op entry.
SPEC.md
— append a section only for features that actually shipped (working, not just started). Describe what it does for a user, not how it's implemented.
GAP_ANALYSIS.md
+
GAP_CONTEXT.md
— keep these two in lockstep. Closed a gap → delete its
```
GAP_ANALYSIS.md
```
line (don't mark it done, remove it) and its
```
GAP_CONTEXT.md
```
entry. Found a new gap → add a terse line to
```
GAP_ANALYSIS.md
```
and the reasoning (deliberate cut / oversight / blocker) to
```
GAP_CONTEXT.md
```
.
PLAN.md
— flip
```
[ ]
```
→
```
[x]
```
for completed tickets, re-prioritize if new requests changed the order, add new tickets for newly surfaced work.
WISDOM.md
— add an entry under the right section (Constraints / Traps / Ditches / Wisdom) only when something genuinely new was learned — a bug that bit you, a pattern worth reusing, a hard constraint discovered. Don't force an entry if the session didn't teach anything new.

For any project-specific scrolls beyond this core set, use the convention

STARTER.md

documents for that specific file — don't default to the generic rules above for a file that says it works differently.

核心六个文件的通用规则（来自

STARTER.md

）：

HANDOFF.md
——覆盖，而非追加。它是一个快照：当前状态、刚刚发生的事情、已知问题/未完成事项。如果本次会话没有实质性变化，可以保持原样，无需添加无意义的条目。
SPEC.md
——仅为实际交付（可正常工作，而非仅启动开发）的功能追加章节。描述该功能对用户的作用，而非实现方式。
GAP_ANALYSIS.md
+
GAP_CONTEXT.md
——保持这两个文件同步。关闭一个差距→删除
```
GAP_ANALYSIS.md
```
中的对应行（不要标记为已完成，直接移除）和
```
GAP_CONTEXT.md
```
中的对应条目。发现新差距→在
```
GAP_ANALYSIS.md
```
中添加简洁的一行，并在
```
GAP_CONTEXT.md
```
中添加原因（故意删减/疏忽/障碍）。
PLAN.md
——将已完成任务的
```
[ ]
```
改为
```
[x]
```
，如果有新请求改变了优先级，则重新排序，为新出现的工作添加新任务。
WISDOM.md
——仅当真正学到新内容时，在相应章节（Constraints / Traps / Ditches / Wisdom）下添加条目——比如遇到的bug、值得复用的模式、发现的硬性约束。如果会话没有学到新内容，不要强行添加条目。

对于核心集合之外的任何项目专属卷轴文件，使用

STARTER.md

中记录的该文件的约定——不要对声明了不同工作方式的文件默认使用上述通用规则。

5. Don't fabricate or over-claim

5. 不要编造或过度断言

If it's unclear whether something shipped versus just started, treat it as unshipped — note it in

HANDOFF.md

's "known issues / open threads" or

PLAN.md

, not as a finished

SPEC.md

entry. When genuinely ambiguous (e.g. whether a gap was actually closed or just worked around), ask rather than guessing — these files are load-bearing for every future session.

如果不清楚某项功能是已交付还是仅启动开发，视为未交付——在

HANDOFF.md

的“已知问题/未完成事项”或

PLAN.md

中记录，而非作为

SPEC.md

中的已完成条目。当确实存在歧义时（例如，某个差距是真正关闭还是仅被 workaround），询问用户而非猜测——这些文件对未来的每一次会话都至关重要。

6. Report what changed

6. 报告更改内容

List which scrolls files were touched and a one-line reason for each. If a file was deliberately left alone despite session activity (e.g. nothing shipped, so

SPEC.md

didn't need a new entry), it's fine to just not mention it — no need to enumerate every file that wasn't touched.

列出被修改的卷轴文件及每个文件的修改原因。如果尽管会话有活动，但某个文件被故意保留原样（例如，没有功能交付，因此

SPEC.md

无需添加新条目），无需提及该文件——无需枚举所有未被修改的文件。

Development

开发

tests/

holds this script's Red/Green regression suite (bash + PowerShell), for maintaining

scripts/session_diff.sh

scripts/session_diff.ps1

themselves — it plays no part in carrying out a user's

/scrolls-update

request. Don't read or run it while executing this skill.

tests/

包含此脚本的红/绿回归测试套件（bash + PowerShell），用于维护

scripts/session_diff.sh

scripts/session_diff.ps1

本身——它在执行用户的/scrolls-update请求时不起作用。执行此技能时，不要读取或运行它。