Automation and Maintenance

Position this module as the shift from sessions to standing arrangements. Modules 3 to 5 were about doing a piece of design work well once: a brief, a plan, a build, a critique. Most of the value teams report after a few months is not from those one-off wins, it is from the chores that now run on their own — the token audit on every pull request, the documentation that regenerates itself, the migration that finally got done. That is what this module covers.

Be explicit about the risk that comes with the territory. Automation removes the human from the moment of execution, which is exactly when problems used to get noticed. Every mechanism in this module is therefore paired with a review point: hooks block rather than fix, scheduled runs report rather than merge, and batch runs work on branches with a reviewer in the loop. The phrase to plant early is reviewable, not trusted.

If the audience has not done Module 5, the examples will still make sense, but the design-system audit and component work from that module are the chores most of this module automates, so a quick recap of what a token audit is may be worth thirty seconds.

The frequency test is the obvious one, but it filters out a surprising amount: the one-off migration to a new framework feels like an automation candidate because it is large, but it runs once, so it is better treated as a supervised batch run than as standing automation. The chores that pay back are the ones that recur on a rhythm — every edit, every pull request, every release, every month.

Boredom is a real signal, not a joke. Design-system maintenance work is mostly rule-based: regenerating prop tables, finding hardcoded values, exporting variants, keeping docs in sync. People defer this work precisely because it is tedious, and deferred maintenance is where drift comes from. Anthropic's own framing for Claude Code is to automate the work you keep putting off, and that maps almost exactly onto this category.

Error cost and verifiability are the safety half of the decision. A documentation regeneration that goes slightly wrong is caught at review and costs minutes. An automated change to the token source of truth that goes wrong propagates everywhere. The question to ask before automating anything: is there a check — a type check, an audit, a visual diff, a human reading a report — that can tell a good run from a bad one? If the answer is no, the chore is not ready to automate, however boring it is.

The mental model to give designers: a skill is a recipe card the agent pulls out when asked. It is not a new capability and not a separate product — it is the prompt you refined over three sessions, written into a file with a name, an argument, and tool limits, so the fourth time costs nothing and produces the same shape of output as the third.

Walk the anatomy briefly. The frontmatter carries the name, a description (which is how the agent knows when the skill applies), an argument hint, and optionally an allowed-tools list that restricts what the skill can touch — a documentation skill has no business running arbitrary shell commands. The body is the procedure itself: read these files, extract this, follow this template, write the result here, report what you did. Exact paths beat vague instructions; the procedure should read like something a careful new colleague could follow.

The versioning point matters more for teams than the syntax does. Because skills live in the repository, they are reviewed like code, improved like code, and shared automatically with everyone who clones the project. When the documentation template changes, the skill changes in the same pull request. That is what turns one designer's clever prompt into a team capability — which is also the bridge into Module 7.

As of June 2026 the same idea appears under slightly different names across platforms — skills, saved prompts, slash commands — and the details of frontmatter fields shift between releases. Teach the pattern, and check the current Claude Code docs for the exact syntax before relying on a specific field.

Read the file top to bottom with the group, because each part answers a question designers actually ask. The argument-hint is what makes it reusable across the whole library: the same procedure documents Button today and DatePicker tomorrow. The allowed-tools line is the quiet safety feature — this skill can read and write files but cannot run shell commands or touch the network, which bounds what a bad run can do.

The numbered steps are deliberately rigid. Exact paths mean the skill fails loudly when the project structure changes instead of guessing. The template reference is what keeps fifty component docs looking like one set rather than fifty improvisations. And step six is the honesty rule: where the source lacks a prop description, the skill reports the gap rather than fabricating one, because plausible invented documentation is worse than a visible hole.

Point out what is not in the file: no judgment about whether the component is well designed, no licence to refactor it while passing through, no decision about what the docs should say beyond what the source says. Skills should encode procedures, not opinions. The opinions stay in the design documentation the skill reads — and in the human who reviews the output.

Walk the map left to right. The left column is the human contribution: naming what actually recurs in this project. That list is different for every team, and writing it down is the first exercise of the module. The middle is the four mechanisms, organised by trigger rather than by technology: hooks fire on every agent edit and are deterministic — a hook that blocks hardcoded colours is a rule, not advice; CI checks fire on every pull request and cannot be skipped or forgotten, which is what makes them gates; scheduled runs fire on a calendar and exist for the slow drift no single change introduces; background agents and fan-out runs fire on demand for batch work — a migration across three hundred files, documentation for every component at once.

The matching principle is the cheapest trigger that catches the problem. Hardcoded values are best caught at the moment of writing, so they belong in a hook or a PR check, not a monthly audit. Meaning drift — a component that is technically token-compliant but no longer matches the documented intent — cannot be caught by any per-change check, so it belongs to the schedule. Asset production has no trigger at all until someone needs the assets, so it is on-demand batch work.

The right column is the part teams skip and regret. Every mechanism ends in evidence read by a person: a report of what changed and what was checked, diffs, gate output. And below the line are the calls that never get automated regardless of mechanism — deprecations, breaking changes, and the judgment about whether a variation is drift or evolution. The map is the module in one picture; the rest of the slides walk its columns.

The table looks like a technology choice but it is really two choices: when does this run, and where does a person look at what it did. Make the group answer the second question for each row, because that is the one that gets skipped. A hook's review point is partly the block itself — the bad change never lands — and partly the normal pull-request diff. A skill's review point is the report it produces at the end of each run, which is why every skill in this module ends with a report step. A CI gate's review point is the findings comment on the pull request, read by the author and whoever approves the merge. A scheduled run's review point is wherever its findings land — and findings that land in a channel nobody owns are the same as findings that were never generated, so route them to a named person. A batch run's review point is doubled: a reviewer agent on every diff during the run, and a human on the pull request at the end.

Note the overlap deliberately. The token discipline problem appears three times — hook, PR gate, scheduled audit — because the layers catch different things at different costs. A hook catches the value at the moment of writing. The PR gate catches what the hook's pattern missed. The scheduled audit catches what no per-change check can see. Layered cheap checks beat one heroic deep one.

As of June 2026, the exact names and surfaces for these mechanisms vary between Claude Code releases and between platforms — saved workflows, routines, scheduled tasks, GitHub Actions. The taxonomy by trigger is stable even where the feature names are not, so teach the column headings rather than the product nouns.

Keep the two defences clearly separated, because conflating them weakens both. Per-change gates run on every pull request: the token audit that fails on raw colour values, the type check, automated accessibility checks plus a keyboard pass on changed routes, and a visual diff of the screens the branch touches. The school's design-QA-on-every-PR workflow is the worked version of this: scoped to the diff, ten to twenty minutes per pull request, findings posted as a comment with severity and evidence. Gates are cheap, unambiguous, and constant — and limited to what someone thought to encode as a rule.

The scheduled audit is the other defence and a genuinely different activity: a monthly or quarterly sweep that asks whether the system as built still matches the system as intended. It catches the drift no single change introduced — a component that is technically token-compliant but no longer matches the documented intent, content that quietly went stale, a web component whose mobile counterpart never got the new variants. Findings need evidence, a severity, and a named decision owner; an audit that feeds an unowned backlog is theatre.

Close with the blind-spot honesty from the school's maintenance article: in the executed case study there, the token audit caught a hardcoded hex value but missed the same mistake written as an arbitrary oklch class, and nothing in a token audit checks contrast at all. A passing gate means the checks you wrote found nothing. It does not mean nothing is wrong — which is one more reason the human review point never goes away.

Asset production is the least glamorous and most reliably valuable category, because the procedure is identical per item and only the volume made it painful. The documentation case from the research is the cleanest example: extract the props interface, follow the template, write the file — repeated for every component in the library, either as a fan-out batch run or as a scheduled run that regenerates docs for whatever changed that week and opens the result as a pull request.

Variant generation works the same way provided the brief points hard at the existing pattern: read the current Button, its stories and tests, and add the destructive and outline variants following exactly the same structure — type union, style mapping, story, test. The phrase that does the quality control is following the exact same patterns; without it, each generated item is a small improvisation and the batch produces fifty slightly different answers. Export sets — icon sizes, image crops, favicon and social variants — are the same shape with even less judgment involved.

Two cautions. First, generated documentation still needs an owner who reads it; plausible documentation that is subtly wrong is worse than a gap, which is why these runs end in a pull request rather than a direct write to main. Second, fan-out is a multiplier on whatever instructions you give it — a flaw in the template or the pattern reference appears in every output at once. Review the first two or three items before letting the batch finish, the same spot-check habit the migration workflow uses.

This is the long tail Module 5 mentioned and never had time for: the migration to semantic tokens that has been in the backlog for a year, the components that are exported but never imported, the DESIGN.md sections that describe values which no longer exist, the dependency bump nobody wants to be the one to merge. They stall for the same three reasons — big, boring, and risky — and the automation pattern addresses each one separately.

The token migration is the worked case worth describing because the school publishes it as a full workflow. The judgment happens before the run: a mapping file, frozen by humans, that records what every legacy value becomes and marks the ambiguous ones as ask. The run itself is a script that loops one migration agent per file with a reviewer agent on every diff — the migration agent is optimised to make changes, the reviewer to refuse them — and ends with a visual recapture comparing key screens against captures taken before the run. Three hundred files becomes a controllable half day, and the flags file becomes the design team's worklist rather than a pile of silent guesses.

The guardrails generalise to every chore on this slide: work on a branch, never main; track progress so the run is resumable; flag instead of guessing; and let the pull request, not the run, be the thing that merges. Dependency bumps get the same treatment with a twist — the design QA gate from the recurring-audits slide runs against the bump branch, so the team sees what the new component library version does to their screens before it ships rather than after.

This slide is the module's centre of gravity, so slow down. The failure mode of automated maintenance is rarely a dramatic breakage — hooks and gates catch most of those. It is the slow accumulation of technically compliant changes that nobody with taste has looked at in months. The system stays consistent and gets quietly worse. The defence is structural, not motivational: design every mechanism so that reading its output is cheap, and assign that reading to a person by name.

Walk the bullets as a checklist against any automation the team is about to set up. The report requirement is non-negotiable and cheap — every skill, scheduled run, and batch script in this module ends with report what you did, what you checked, and what you left alone, because the absence of changes is evidence too. Attaching gate output matters because a summary that says checks passed is a claim, not evidence. Named owners matter because findings posted to a channel decay into wallpaper within a month. And the no-self-merge rule is the bright line: the run can open the pull request, it cannot approve it.

The last bullet draws the boundary the school's maintenance article calls the almost: deprecations, renames, breaking changes, intentional variation, and taste are decision rights, not capability gaps. The agent can produce the impact analysis — every consumer of a token, every surface a breaking change touches — and that genuinely changes how confidently humans decide. It does not change who decides. Automation that quietly absorbs those calls has not saved anyone time; it has moved the design decisions to the entity with the least accountability for them.

This trace is a representative composite of the documentation pattern in the book research and this school's workflows, run on a small component library — present it as the shape of the journey, not as a benchmark. The point of showing it as a table is the progression: the same procedure moves from a session to a skill to a schedule, and at every stage the question what does the human review has a concrete answer.

Week one is deliberately manual and deliberately slow. The first run is where the template gets fixed, the prop-extraction rules get sharpened, and the honesty rule — report missing descriptions, do not invent them — gets added after the agent helpfully fabricated one. Resist the urge to automate before this shakedown; a skill written from an unrefined prompt just repeats its flaws faster.

Week two freezes the procedure into a SKILL.md and the cost per component drops to minutes, most of which is the human reading the output. Week three adds the trigger: a scheduled run that checks which component files changed in the past week, regenerates only those docs, and opens a pull request. The deliberate choice is that the schedule produces a PR, not a merge — fifteen minutes of review a week is the standing price, and it is the cheapest line item in the whole arrangement. The steady-state row is the actual payoff: documentation drift stops being a quarterly cleanup and becomes a weekly non-event, and the gaps the skill reports become a worklist instead of a surprise. The quarterly read of the skill itself is the maintenance of the maintenance — procedures drift too.

Like the exercises in earlier modules, this one is paper-first: the goal is the procedure, not the syntax, and the syntax changes between releases anyway. Steer people towards chores they have genuinely done at least twice with the agent — documentation regeneration, a token check, an export set, an audit of one flow. The most common mistake is picking something aspirational and large; the second most common is picking a judgment call, like deciding which components to deprecate, and discovering at step three that there is no procedure to write.

The frontmatter forces the scoping decisions: what argument does this take, and what is the smallest set of tools it needs. The numbered steps force the precision: exact paths, an explicit template or pattern reference, and the flag-do-not-guess rule wherever the source might be ambiguous. The report step and the named reviewer connect the exercise back to the reviewability slide — a skill without a report is a skill nobody can supervise.

If running this live, have two or three people read their steps aloud and ask the room a single question: could a careful new colleague follow this without asking anything? Where the answer is no, the gap is usually a missing path, an unstated convention, or a hidden judgment call — exactly the things that would have made the automated runs inconsistent. Participants who finish early can write the second half: the trigger, the review point, and what would convince them after a month that the skill is working.

Recap by walking the bullets, but emphasise the through-line: nothing in this module made the agent more capable. Every gain came from writing a procedure down, choosing when it runs, and deciding who reads the result. That is process design, which is to say it is design — and it is why this module sits with the designer rather than with whoever owns the build pipeline.

Remind the group of the two artefacts they now have on paper: the chore inventory implied by the automation map and the draft skill from the exercise. The practical homework is to take the single strongest candidate and walk it through the three-week progression from the worked example — manual session, saved skill, scheduled run — rather than trying to automate the whole inventory at once. One standing arrangement that the team trusts is worth more than five that nobody reviews.

Preview Module 7 concretely: everything so far has treated Claude Code and the repository as the whole world. The next module connects it outward over MCP — design canvases, browsers and screenshots, tickets, analytics — and then deals with the harder half of scale: shared harness files, team conventions, cost, and a rollout that starts with a pilot rather than a mandate. The skills and scheduled runs built in this module are exactly the things a team shares, which is why this module comes first.