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

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

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

Steps

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

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.

2. Read STARTER.md as the authoritative map

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.

3. Establish what actually happened this session

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.

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

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.

5. Don't fabricate or over-claim

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.

6. Report what changed

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.

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.

scrolls-update

NPX Install

Tags

SKILL.md Content