git:20260908.94a260a to git:20260928.a0f6e09

+ | **Entry point** | Adapts to existing code | Mandatory brainstorm; on an existing design, asks preserve, partial or redesign |

+ 1. **Never skip the brainstorm.** Not even if the user says "just make it look good." Especially then. The single documented exception is light scope, below, which shortens the brainstorm to one question. It never removes it. With nobody answering, see "When nobody is answering": the questions are answered from the brief, as assumptions.

+ 3. **Never proceed without the theses validated.** Visual + interaction, both explicitly approved. The one exception is light scope, below: no visual identity is at stake there, so the interaction thesis alone is required - and it is still validated explicitly, never assumed. With nobody answering, see "When nobody is answering".

+ 5. **Every animation respects the interaction thesis.** Timing, easing, forbidden patterns - no exceptions.

+ 6. **Never install a dependency without asking.** With nobody answering, never install one (see "When nobody is answering").

+ 8. **The audit is not optional.** Phase 5 always runs, even if the user seems happy. On light scope it shortens to the quick check - thesis against code, reduced-motion, exit animation, 60fps - but it never disappears.

+ | 5 AUDIT | full design-audit sub-skill | the quick check: thesis against code, reduced-motion, exit animation, 60fps |

+ > **A. Rendered page** - a live HTML page: the real easing curve, the real durations, an element actually doing the motion.

+ | Scope is medium or full, web stack | A - rendered page |

+ | A full visual identity or design system is on the table | A - rendered page |

+ | No dev server, or the repo must not be written to | A - rendered page |

+ | Host is Cowork and there is no project checkout to write into | A - rendered page, B is unavailable |

+ **The choice sticks for the whole session.** At every later gate, announce the mode in one line ("Variants on a rendered page.") and go. Do not reopen the menu. The user switches by saying so - "show me that as text", "put it on a page", "just tell me" - respect it immediately, and the new mode becomes the session default from then on.

+ if [ -d /mnt/skills/plugins ] || [ -d /mnt/skills/user ]; then

+ | Host | A - rendered page | C - inline |

+ | claude.ai | Rendered natively as an artifact. Just produce one. | Written out in the conversation. |

+ | Claude Code | The `Artifact` tool when the session has it, else the capability rule below. | Written out in the conversation. |

+ | unknown (any other host) | The capability rule below. | Written out in the conversation. |

+ **A, by capability.** Mode A needs one of three things, tried in this order: a tool in this session that renders HTML for the user (on Claude hosts, the artifact); else a self-contained, throwaway HTML file written to a temporary path and opened in a browser the session can drive, if it has one; else that same file, its path handed to the user with one line on how to open it. Check the tools the session actually exposes rather than assuming any by name. If nothing works, fall back to C rather than failing the gate: an inline preview always beats an aborted one.

+ - **The message that carries it names the thesis in plain text.** Whatever the mode, it opens

+ with the thesis in one sentence, labelled (`Interaction thesis:` or `Visual thesis:`), then its

+ `Allowed patterns:` line, says in one line that the page is the proposal and not the build, and

+ ends with the validation question.

+ It holds no implementation: code starts in a later turn, after a yes. Someone who picked A or B

+ must never have to look for where the thesis went.

+ <!-- genjutsu:shared:headless:start -->

+ ## When nobody is answering

+

+ Some sessions have no human on the other end: an eval harness, a CI job, another agent driving

+ this skill. You know it because the request or the host says so (a non-interactive run, "do not

+ ask questions", a prompt that pre-answers the gates), never because one question went unanswered

+ for a while. When the request pre-answers a gate, that answer stands: the gate is answered, not

+ skipped.

+

+ In such a session every gate still produces its output. What changes is that nobody validates it:

+

+ - **Discovery and brainstorm questions:** do not ask them. Answer each from the brief and the

+ scan, and name every answer as an assumption in the thesis.

+ - **Preview gate:** take the default the menu recommends for this scope and stack, announce it in

+ one line, and go on.

+ - **Thesis gate:** take the thesis you would have proposed, say in one line that it is not

+ validated, and go on. The final report prints it, marked **UNVALIDATED**.

+ - **Dependencies:** never install one. Where the thesis wants a library the project does not

+ have, use the stack's native APIs and name the missing dependency in the final report.

+

+ Everything else holds: the thesis is written before any code, the modules are loaded, and the

+ audit reports evidence. A headless run skips the waiting, never the work.

+ <!-- genjutsu:shared:headless:end -->

+

+ **Tell the block where this skill lives.** The block's first line reads `GENJUTSU_SKILL_DIR`.

+ Claude Code fills it in by itself. On any other host, put one line in front of the block, in the

+ same shell call, naming the directory you read this file from:

+ `GENJUTSU_SKILL_DIR='/absolute/path/to/paint'`. When the genjutsu router printed a

+ `GENJUTSU_SKILL_DIR=` line, use that value as it is.

+

+ **This block defines shell state, and shell state does not survive between shell calls.**

+ `$SKILL_BASE`, `load_skill` and `load_ref` exist only inside the single shell call that ran

+ this block. Any later phase - and every phase after a user-validation gate is a later phase -

+ starts from nothing. So: **re-emit this whole block in the same shell call as the

+ not define it: the path resolves to `/<name>/...`, the `cat` fails, and the module is lost.

+ **If the block prints `could not find the genjutsu modules`, stop the pipeline.** Show the

+ user the message, install command included, and do nothing else: every later step depends

+ on the modules, and running without them produces exactly the generic output this skill

+ exists to prevent.

+

+ GENJUTSU_SKILL_DIR="${GENJUTSU_SKILL_DIR:-${CLAUDE_SKILL_DIR}}"

+ # Resolution order, first hit wins:

+ # 0. claude.ai, /mnt/skills/plugins (or the older /mnt/skills/user): the

+ # genjutsu bundle.

+ # 1. This skill's own directory: its _jutsu, or the _jutsu next to it.

+ # 2. ${CLAUDE_PLUGIN_ROOT}/skills/_jutsu, when Claude Code substituted it.

+ # 3. Bounded probes: .claude/skills and .agents/skills from $PWD upward, then

+ # the skills directories installers write to, then /sessions (Cowork).

+ # 4. The Claude Code plugin cache, newest version. Last on purpose: an old

+ # plugin install must never win over a newer bundle.

+ # Resolved from scratch every time. A cache was tried here and removed: after a

+ # plugin update the old version directory is still on disk, so a cached path

+ # passes an "is it a directory" check and serves the previous release.

+ # A _jutsu directory counts only if it holds motion-principles. The shared

+ # skills directory of npx serves about 80 agents, so a directory name proves

+ # nothing. The entry file is named SKILL or GUIDE depending on the artifact

+ # (the bundle renames it at packaging time), so the name is assembled from

+ # parts: spelled out in full, the packaging step would rewrite it too.

+ genjutsu_is_jutsu() {

+ for d in SKILL GUIDE; do

+ [ -f "$1/motion-principles/$d.md" ] && return 0

+ return 1

+ }

+

+ # Print the first genjutsu _jutsu among the candidate paths read on stdin.

+ genjutsu_first_jutsu() {

+ while read -r jutsu_c; do

+ genjutsu_is_jutsu "$jutsu_c" && { printf '%s\n' "$jutsu_c"; return 0; }

+ # 0. claude.ai mounts uploaded skills under /mnt/skills/plugins/<name>/ (seen on

+ # 2026-09-28), next to the user's other skills; /mnt/skills/user before that.

+ # GENJUTSU_CLAUDE_AI_ROOT stands in for /mnt/skills in the test suite only.

+ # Only a _jutsu holding motion-principles counts: a mount without genjutsu in it

+ # must never pass for a resolved base.

+ genjutsu_claude_ai="${GENJUTSU_CLAUDE_AI_ROOT:-/mnt/skills}"

+ for claude_root in "$genjutsu_claude_ai/plugins" "$genjutsu_claude_ai/user"; do

+ [ -z "$SKILL_BASE" ] && [ -d "$claude_root" ] || continue

+ SKILL_BASE="$(find -L "$claude_root" -maxdepth 2 -type d -name _jutsu 2>/dev/null | genjutsu_first_jutsu)"

+ done

+ # 1. This skill's own directory. Empty means unknown: never probe "/_jutsu".

+ if [ -z "$SKILL_BASE" ] && [ -n "$GENJUTSU_SKILL_DIR" ]; then

+ SKILL_BASE="$(printf '%s\n' "$GENJUTSU_SKILL_DIR/_jutsu" "$GENJUTSU_SKILL_DIR/../_jutsu" | genjutsu_first_jutsu)"

+ # 2. Claude Code plugin root.

+ if [ -z "$SKILL_BASE" ] && [ -n "${CLAUDE_PLUGIN_ROOT}" ]; then

+ SKILL_BASE="$(printf '%s\n' "${CLAUDE_PLUGIN_ROOT}/skills/_jutsu" | genjutsu_first_jutsu)"

+ fi

+ # 3. Bounded probes, following symlinks (npx links .claude/skills/<name> to

+ # .agents/skills/<name>). The case guard stops the walk at "/", "." or "".

+ probe_dir="${PWD:-$(pwd)}"

+ probe_n=0

+ while [ -z "$SKILL_BASE" ] && [ "$probe_n" -lt 24 ]; do

+ probe_n=$((probe_n + 1))

+ SKILL_BASE="$(find -L "$probe_dir/.claude/skills" "$probe_dir/.agents/skills" -maxdepth 2 -type d -name _jutsu 2>/dev/null | genjutsu_first_jutsu)"

+ case "$probe_dir" in /|.|"") break ;; esac

+ probe_dir="$(dirname "$probe_dir")"

+ done

+ for probe_root in "$HOME/.agents/skills" "$HOME/.claude/skills" "$HOME/.codex/skills" \

+ "$HOME/.cursor/skills" /mnt/.claude/skills; do

+ [ -z "$SKILL_BASE" ] && [ -d "$probe_root" ] || continue

+ SKILL_BASE="$(find -L "$probe_root" -maxdepth 2 -type d -name _jutsu 2>/dev/null | genjutsu_first_jutsu)"

+ done

+ if [ -z "$SKILL_BASE" ] && [ -d /sessions ]; then

+ SKILL_BASE="$(find -L /sessions -maxdepth 8 -type d -path '*/.claude/skills/*/_jutsu' 2>/dev/null | genjutsu_first_jutsu)"

+ fi

+ # 4. Claude Code plugin cache, newest version first. Numeric version

+ # directories only, so a bare marketplace clone never wins.

+ if [ -z "$SKILL_BASE" ] && [ -d "$HOME/.claude/plugins/cache" ]; then

+ SKILL_BASE="$(find "$HOME/.claude/plugins/cache" -maxdepth 6 -type d -path '*/genjutsu/[0-9]*/skills/_jutsu' 2>/dev/null | sort -V -r | genjutsu_first_jutsu)"

+ fi

+ [ -n "$SKILL_BASE" ] && SKILL_BASE="$(cd "$SKILL_BASE" 2>/dev/null && pwd -P)"

+ # Stop instead of running the pipeline without its modules. Name every root that

+ # was tried, so a new layout can be reported instead of guessed.

+ if [ -z "$SKILL_BASE" ]; then

+ echo "genjutsu: could not find the genjutsu modules (a _jutsu directory holding motion-principles)." >&2

+ echo " cast and paint do not work without them. Install the full bundle:" >&2

+ echo " any agent npx skills add https://genjutsu.athevon.dev -g" >&2

+ echo " Claude Code /plugin marketplace add AThevon/genjutsu, then /plugin install genjutsu" >&2

+ echo " claude.ai upload genjutsu.zip in Customize > Skills" >&2

+ echo " npx skills add AThevon/genjutsu installs cast and paint without their modules." >&2

+ echo " Tried: /mnt/skills/plugins, /mnt/skills/user, GENJUTSU_SKILL_DIR (${GENJUTSU_SKILL_DIR:-empty}) and its parent," >&2

+ echo " \$CLAUDE_PLUGIN_ROOT, .claude/skills and .agents/skills from \$PWD upward," >&2

+ echo " ~/.agents/skills, ~/.claude/skills, ~/.codex/skills, ~/.cursor/skills," >&2

+ echo " /mnt/.claude/skills, /sessions, ~/.claude/plugins/cache." >&2

+ echo "genjutsu: stop the pipeline here and show this message to the user." >&2

+ return 1 2>/dev/null || exit 1

+ echo "genjutsu: modules from $SKILL_BASE" >&2

+ # Print a module's entry file. A missing module does not stop the pipeline (a

+ # partial claude.ai upload is legitimate), but it is announced, and the final

+ # report lists it: shell state does not survive, so the model keeps the list.

+ for d in SKILL GUIDE; do

+ if [ -f "$SKILL_BASE/$1/$d.md" ]; then

+ cat "$SKILL_BASE/$1/$d.md"

+ echo "genjutsu: sub-skill '$1' NOT LOADED - not found under $SKILL_BASE. Carry on, and list it under 'Modules not loaded' in the final report." >&2

+ return 1

+

+ # Print one reference file of a module: load_ref <module> <path inside it>.

+ load_ref() {

+ if [ -f "$SKILL_BASE/$1/$2" ]; then

+ cat "$SKILL_BASE/$1/$2"

+ return 0

+ fi

+ echo "genjutsu: reference '$1/$2' NOT LOADED - not found under $SKILL_BASE. Carry on, and say so in the final report." >&2

+ return 1

+ }

+ All sub-skills are loaded via `load_skill <name>` (defined above), which prints the module's

+ entry file, or a `NOT LOADED` line when the module is missing, and carries on: keep the list, the

+ final report needs it. When the block cannot find the modules at all, it stops, and so does the

+ pipeline. Every phase below that loads something must re-emit the resolution block in the same

+ shell call: the phases are separated by user gates, and nothing carries across them.

+ ### Phase 1 - BRAINSTORM (mandatory, never skip)

+ **Declare your read before the first question.** The scan has run and the request is in front of

+ you. Before the first brainstorm question, say what you already believe in one line, so the user

+ corrects a wrong premise before it steers every question after it:

+

+ > "My read so far: <what> for <whom>, heading toward <direction>, on <stack>. Correct me before I ask anything."

+

+ `<what>` is the product and `<whom>` the audience as the request states them, `<direction>` the

+ mood the request or the existing design suggests, `<stack>` what the scan found. A slot you cannot

+ fill is said as unknown ("for an audience I can't tell yet"), never guessed; the unknown slots are

+ where the brainstorm starts. The line is its own message: send it and wait. A correction replaces

+ the slot it names; a go-ahead means the read stands. It is not a brainstorm question and does not

+ count against light scope's single question, and it is not a thesis: nothing in it is validated

+ until Phase 2. When no human is in the session to answer, state the read and carry on with it as

+ written.

+

+ **If the project already has a visual identity** (CSS variables or a Tailwind theme, `Theme.kt` /

+ `Color.kt`, `Color+App.swift` or an asset catalog, a logo, a live brand):

+

+ **First, take the inventory of what is already there.** On a web stack, in one shell call,

+ re-emit the skill-base block and run `python3 "$SKILL_BASE/design-audit/scripts/audit.py" . --group tells`.

+ Show the result as one short block, **What this project already does by reflex**, counted by

+ family, with two or three `file:line` examples each. Each of them is settled in the theses,

+ according to the mode the question below sets: in preserve mode they stay by default and go into

+ the `Allowed patterns:` line as the brand's own; in partial mode they go by default inside the

+ areas the user named; in redesign mode they go by default everywhere. The user can keep or drop

+ any one of them by name at the thesis gate.

+

+ Ask exactly one mode question during brainstorm, right after the legacy question when both apply:

+

+ > "This project already has a look. Should I preserve the brand and build within it, change part of it, or redesign it?"

+

+ - **Preserve** - the theses describe the brand as it is and add only what it lacks (motion,

+ states, missing steps in a scale). Existing tokens stay.

+ - **Partial** - the user names what may change ("type and motion, not the colors"). The theses

+ change the values in those areas, under the existing token names, and nothing else.

+ - **Redesign** - the theses replace the whole visual layer, existing tokens included.

+

+ The chosen mode goes into the visual thesis as one explicit clause ("preserving the existing

+ palette and logo"), so the Phase 2 gate validates it with everything else. What each mode lets

+ the thesis replace is in "Existing Project Protocol" below. Light scope does not ask: no visual

+ identity is at stake there, so it is preserve by definition.

+

+ 1. **Product** - What is it (app, landing page, portfolio, SaaS, e-commerce, blog, dashboard...), and what is true of it that its closest neighbour, or a template, could not claim?

+ 2. **Audience** - Who uses it? (devs, designers, general public, enterprise, kids, luxury...)

+ 3. **Mood** - 3 to 5 adjectives that define the visual feel

+ 4. **References** - Sites, screenshots, mood boards the user brings. Never suggest famous ones yourself: that anchors the thesis on someone else's look.

+ 5. **Tech stack** - What's already in place? Or starting from scratch?

+ **How to ask:** One question at a time, starting with the least obvious domain. If you already know the tech stack from scanning `package.json`, don't ask - start with mood or audience instead. Each answer reshapes how you ask the next question.

+ 1. **Validate** - "That's a starting point. Let's make it precise."

+ 2. **Go back to the product** - "Clean compared to what? Tell me one thing that is true of this product and that its closest competitor could not say about itself." Answer a mood word with a fact about the product, never with another brand's look: "like Stripe, like Linear, like Apple" anchors the thesis on three famous defaults.

+ 3. **Reframe** - "What would feel *wrong*? What sites make you cringe? That's just as useful."

+ 4. **Name the consequence** - "This choice drives the entire color palette and typography. Worth spending a minute on."

+ **Never** interpret a vague answer as confirmation. "Yeah something like that" means dig deeper - ask which part of "that" resonates.

+ ### Phase 2 - THESIS (define direction, get validation)

+ - **Color direction** - dark/light, palette family, accent color

+ - **Typography spirit** - the display face by name and why this one, or `display face: undecided, chosen at the design-system gate`; serif/sans/mono, weight usage, size contrast

+ - **Spacing philosophy** - dense/airy, base unit feel

+ - **Component style** - rounded/sharp, bordered/filled, elevated/flat

+ **Guessability test:** could someone write this thesis from the product category alone (a fintech gets navy and a clean sans, a design studio gets an editorial serif on paper)? Then it is the category's default, not a decision: rewrite it from what is true of this product.

+

+ - **Timing range** - fast (100-200ms), medium (200-400ms), or slow (400ms+)

+ - **Hover behavior** - what happens on hover

+ - **Scroll behavior** - reveals, parallax, or nothing

+ - **Forbidden patterns** - what this project will NOT do

+ > Example: "Fast and dry transitions (100-200ms), hover with subtle scale (1.02), scroll-triggered reveals with stagger, no bounce or elastic - all sharp ease-out."

+ **Under the two theses, one line naming what it allows.** `Allowed patterns:` followed by every

+ deliberate device the design relies on that a reader could take for decoration or habit: mono

+ labels, hairline rules, a paper ground, grain, a glow, a looping animation, a code label, a live

+ clock. Write `Allowed patterns: none` when there are none. The audit reads this line: a tell

+ counts as allowed only when it is listed here, so a mood word never lets one through, and the

+ user sees the list before saying yes.

+

+ **Wait for explicit user validation of BOTH theses before moving on.** If the user pushes back, don't start over - ask what feels wrong and adjust.

+ #### The three dials (after validation)

+

+ Once both theses are validated, read three values off them. Phase 3 passes them to `search.py`

+ as 1-10 dials:

+

+ | Dial | Read it from | 1 | 10 |

+ |---|---|---|---|

+ | `--variance` | the visual thesis: layout and component style | centered, symmetric, minimal | bold, asymmetric, experimental |

+ | `--motion` | the interaction thesis: timing range, scroll behavior, forbidden patterns | subtle | complex, choreographed |

+ | `--density` | the visual thesis: spacing philosophy | spacious | dense, dashboard |

+

+ Derive each value from a clause of the validated theses, never from the raw brief and

+ never from a default. "Generous whitespace" settles density low; "fast and dry, no scroll

+ reveals" settles motion low. A dial the theses do not settle is left out of the call entirely:

+ an unsent dial changes nothing, a guessed one biases the lookup toward something nobody

+ approved. Write each value down with the clause it came from; they are shown with the design

+ system before Phase 4.

+

+ Light scope has no Phase 3, so it sets no dial.

+

+ ### Phase 3 - DESIGN SYSTEM

+ **On a web stack, load `tells` first** (light scope never reaches this phase), in a shell

+ call of its own, before the design-system query. Phase 2 ended in a user gate, so re-emit the

+ resolution block in that call:

+

+ ```bash

+ # (skill-base block re-emitted above this line)

+ load_skill tells

+ load_ref tells references/web.md

+ ```

+

+ The query below answers from a static dataset that has never seen the project. `tells` is what

+ lets you recognise which of its proposals are reflexes the validated thesis never asked for.

+

+ new shell call and `$SKILL_BASE` no longer exists.** Re-emit the resolution block from "Sub-skills

+ # Append only the dials Phase 2 settled (see "The three dials"); drop each flag the theses

+ # left open, and never send a dial with a made-up value.

+ --design-system -f markdown \

+ --variance <V> --motion <M> --density <D>

+ **What the dials do on this path.** With `--design-system -f markdown`, `--variance` biases which

+ style the lookup picks and `--motion` attaches a motion snippet of the matching intensity: both

+ change the proposal. `--density` does not. On this path it only prints its label under "Design

+ Dials": the spacing scale it maps to is written by `--persist` alone, and paint does not persist.

+ So derive the spacing scale in MASTER.md by hand, from the spacing philosophy of the visual

+ thesis, and let the density label say what that scale has to feel like. The motion snippet is

+ GSAP code: on any other stack read it for its duration and easing only, and never install GSAP

+ because of it.

+

+ Filter it twice before keeping anything: through the thesis, and through `tells`, loaded just

+ before this call on a web stack (on Compose and SwiftUI `tells` is not loaded, and the thesis

+ filters alone). The dataset matches keywords, so it hands back exactly the reflex picks `tells`

+ describes:

+

+ - **The display face**, serif or sans, stays only when the visual thesis names it and says why

+ that face: what it carries for this product that another would not. "Creative", "premium" and

+ "editorial" summon an editorial serif; "clean", "modern" and "SaaS" summon a heavy grotesque.

+ Neither set of words is a reason, and trading one reflex for the other is not a decision.

+ When the thesis left the face undecided, choose it here: name it and say why in one line. That

+ line amends the visual thesis when the design system is validated, and Phase 4 and the audit

+ read the amended sentence, never the original gap.

+ - **A warm paper ground** (a faintly warm off-white behind near-black ink and one red accent) is

+ the palette the model reaches for on almost any brief. It stays only when the thesis says why

+ this product belongs on paper.

+ - **Glassmorphism**, which the dataset attaches to "SaaS", does not pass unless the thesis asks

+ for it by name.

+ - Anything else in the output that `tells` lists as a reflex is held to the same test: named in

+ the thesis, or dropped. The one line that says what you took and dropped also says what this

+ filter removed.

+

+ paint never passes `--persist`, so the component values hardcoded in the MASTER.md template of

+ `design_system.py` never reach the project: MASTER.md is written here, from the validated theses

+ and the tokens kept above. If paint ever persists, rewrite those component values from the

+ tokens before keeping the file.

+

+ - **Color palette** - Primary, secondary, accent, neutrals, semantic (success/warning/error/info). Light + dark if needed.

+ - **Typography** - Font stack, size scale (fluid or fixed), weight usage, line-height rules.

+ - **Spacing** - Base unit, scale (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px...).

+ - **Radii** - Border radius scale (none, sm, md, lg, full).

+ - **Shadows** - Elevation levels (0-4), consistent with visual thesis.

+ - **Base components** - Button, input, card, badge, link - styled per the theses.

+ - **Motion tokens** - Duration scale (fast/normal/slow), easing names, stagger delay.

+ - **Stitch** - Generate mockups/wireframes

+ - **Nano Banana** - Generate visual assets (illustrations, icons, backgrounds)

+ - **21st.dev Magic** - Generate UI components from descriptions

+ If MCPs are not available, skip gracefully - the design system + code implementation is the core path.

+ Present the design system in the session's preview mode - announce the mode in one line, don't reopen the menu - and get validation before implementing anything. If Phase 3 chose the display face, show its one-line reason with it: validating the design system validates that amendment to the visual thesis. A palette and a type scale listed as hex codes and pixel values in a transcript are precise and completely unreviewable; every token in MASTER.md is about to be applied everywhere, so this is the cheapest place to catch a wrong one.

+ Show the dials beside it: each value sent to `search.py` with the thesis clause it came from,

+ and each dial left out with the reason.

+

+ ### Phase 4 - IMPLEMENT

+ **Always load** (via `load_skill <name>`, defined above: a missing module prints `NOT LOADED` and the pipeline carries on, so keep the list for the final report):

+ **One module per shell call.** The output of a shell call over about 30,000 characters does not

+ arrive inline: you get a 2,000-character preview and a file path, and a module you could not

+ read is a module you did not load. So each loading call re-emits the skill-base block and loads

+ one module, which keeps its output under 25,000 characters: no module entry file is over that

+ cap, and `validate-skills.py` keeps it that way. Keep the tally as you go: `load_skill` prints

+ `NOT LOADED` for a missing module and carries on, and the final report lists both. Load each

+ module whole: never pipe `load_skill` or `load_ref` into `head`, `tail`, `sed`, or `grep`, since

+ the batching rule above already keeps each call under the limit, and a truncated module is a

+ module not loaded.

+

+ | Web stack and scope is medium or full | `load_skill tells` (dedicated call, with `references/web.md`, see below) |

+ **`tells` gets a shell call of its own.** With its web reference it weighs about 20,000

+ characters, too close to the point where a shell call's output stops arriving inline to share a

+ call with any other module. Re-emit the skill-base block in that call, then:

+

+ ```bash

+ # (skill-base block re-emitted above this line)

+ load_skill tells

+ load_ref tells references/web.md

+ ```

+

+ It loads after the thesis gate and before any visual choice is frozen: the validated thesis says

+ which patterns are wanted, and `tells` names the reflexes nobody asked for. Never on a Compose or

+ SwiftUI stack, never on light scope. In paint this row is already met: Phase 3 loads `tells`

+ before the design-system query.

+

+ - Work **page by page** or **component by component** - never try to do everything at once.

+ ### Phase 5 - AUDIT (never skip)

+ - [ ] **Thesis against code.** First, because every check below assumes the code is the thesis

+ that was validated. For each promise the validated thesis actually makes (durations,

+ easing, springs, palette, type, layout family) give the `file:line` that holds it, or

+ "not found". A thesis that makes no palette or type promise, an interaction thesis alone,

+ gets no palette or type line. A promise with no `file:line` is a problem found, not a

+ pass. Honest downgrade: when promised motion cannot be shipped working, ship the

+ static version, say so here, and name the promise that was dropped; it counts as a

+ problem found. Never ship motion that is half broken to keep a promise on paper.

+ Evidence: one line per promise, e.g. `hover 180ms ease-out - src/Card.tsx:42`.

+ - [ ] **Tells confronted with the thesis.** Only when `tells` was loaded. In one shell call,

+ re-emit the skill-base block and run

+ `python3 "$SKILL_BASE/design-audit/scripts/audit.py" . --group tells`, whether or not

+ `design-audit` was loaded. Evidence, for each finding: either the problem you kept, with its

+ `file:line`, or the entry of the thesis's `Allowed patterns:` line that names it. A kept tell

+ counts among the problems found. An allowed one is listed as "allowed by the thesis", with

+ that entry quoted, and is not a problem. The manual reads `tells` lists (fake product in

+ divs, repeated layout family, floating corner paragraph, copy register, copy held in

+ JavaScript data) are reported the same way.

+ Each finding has one of three outcomes, never a fourth: **allowed by the thesis**, its

+ `Allowed patterns:` entry quoted; **not this tell**, only when the detection contradicts the

+ entry's own marker (the loop reports a real loading state, the blur is a modal backdrop, the

+ matched line is not displayed text), with the `file:line` that proves it and never on a matter

+ of taste; or **a problem**. Fix before you report, and only what this run introduced: a problem

+ on a line this run wrote (read `git diff` when the project has one) is removed or rewritten,

+ then this check runs again, two passes at most, and what still fails is reported with its

+ `file:line`. A tell that was already in the project, on a line this run did not write, is

+ never changed here: it is listed for the user. Nothing on the protected list of an existing

+ project (public token names, URLs, navigation labels, form field names, logo, legal mentions)

+ is changed by this step.

+ **Report the two groups separately**, with the counts. "11 checked, 2 problems found, 8 handed

+

+ **Close the report with the modules**, always, as two lines of their own:

+

+ ```

+ Modules loaded: motion-principles, framer-motion, design-audit

+ Modules not loaded: none

+ ```

+

+ `Modules not loaded` names every module a `load_skill` call reported as `NOT LOADED`, and every

+ module the load tables called for that was never requested. Write `none` only when both are

+ empty. Shell state does not survive between calls, so this list is yours to keep from the first

+ load to the last: nothing in the shell remembers it for you.

+ 2. Ask the mode question in Phase 1: preserve the brand, partial, or redesign. The mode decides what the thesis may replace: nothing already defined in preserve mode, only the areas the user named in partial mode, the whole visual layer in redesign mode

+ 3. In Phase 4, existing design tokens are **replaced only in redesign mode**. In preserve mode, MASTER.md takes the existing tokens as they are and adds the new ones beside them. In partial mode, it keeps every existing token name, changes the values only in the areas the user named, and adds new tokens beside them

+ 4. Preserve functionality and layout structure - only replace the visual layer

+ In all three modes, none of these change without the user's explicit agreement, asked item by

+ item: public token names (code outside this project may import them), URLs and routes,

+ navigation labels, form field names, the logo, legal mentions.

+ Before writing any token file, show the diff between the existing tokens and the new ones

+ (renamed, changed, added, removed) and wait for approval. After writing, build with the stack's

+ own command: `tsc --noEmit` or the project's build script (`npm run build` or its pnpm / yarn

+ equivalent) on web, `./gradlew assembleDebug` on Android, `xcodebuild -scheme <scheme> build` on

+ Apple. When the build cannot run here, hand it over marked **UNVERIFIED** with the exact command,

+ like the handed-over group of the audit.

+

+ The mode answers "rebuild or enhance?" inside paint: preserve mode enhances a brand without

+ replacing it. `/genjutsu:cast` stays the entry point for one effect or one component.

+

+ ## Red Flags - You're About to Violate This Skill

+ | "The user already said 'minimal dark' - I have enough for a thesis" | Two words aren't five domains. Keep asking. |