open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

feat(claude-design): add 03-iteration-and-session cascade + recovery reference

Browse source 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-05-18 12:16:53 +02:00
commit 2a851f0e12
1 changed files with 256 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

256
plugins/claude-design/skills/claude-design-facilitator/references/03-iteration-and-session.md Normal file
View file

@ -0,0 +1,256 @@
# Iteration and session — Tweak / Comment / Chat cascade and recovery
**Last updated:** 2026-05-17 | **Verified:** research/04-iteration-mechanics-recovery.md
**Status:** Beta (Labs research preview)
**Captured-on date:** 2026-05-16
This file documents three things in order of operational urgency: which iteration surface to use when, when to break a session, and how to recover when iteration stops landing. The cost asymmetry between Tweak / Comment / Chat is the single largest leverage point in a Claude Design workflow.
---
## 1. The three-surface cascade
Claude Design exposes three edit surfaces with asymmetric token costs and asymmetric scope:
| Surface | Token cost | Scope | When to use |
|---------|-----------|-------|-------------|
| Tweak panel | Zero | Surgical, per-control | Anything Claude pre-derived at generation time |
| Inline comment | Zero on success | Component-scoped, in-component | Targeted in-component text or visual change |
| Chat | One full turn | Whole artifact | Structural change, aesthetic pivot, new section |
### Tweak panel
The Tweak panel is the per-artifact set of controls and sliders Claude pre-derives during generation. Each artifact comes with its own Tweak surface — section reordering, variant swap, density slider, spacing scale, color temperature, typography scale, padding / radius / shadow. The controls are surgical and zero-token: applying them does not consume a chat turn or budget time. They are also lossy-free — the artifact does not regenerate; the controls operate on the existing render.
Tweak panel coverage is per-artifact. If Claude did not pre-derive a control for a dimension, that dimension is not Tweak-editable. The first move is always to check the Tweak panel: most dimensions an operator wants to refine after the first generation are already there.
Operator-actionable mantra (the synthesis from `research/04`):
> Anything Claude pre-derives at generation time is surgical thereafter; new controls cost one chat turn for setup.
### Inline comments
The comment surface lets the operator click anywhere on the rendered artifact and attach a directive — "make this section narrower", "use a darker shade for this header", "remove this icon". Comments are surgical when the change is in-component (text edit, color tweak, sizing within an existing container) and they cost zero tokens on success.
Two failure modes the operator should know:
1. **Vanish bug** — comments sometimes disappear after submission with no edit applied. Anthropic has acknowledged this (community-cited; the workaround is to paste the comment text directly into chat as a follow-up turn).
2. **Structural-container failure** — comments cannot add a new structural container (a new section, a new column, a new modal). The model interprets the directive but produces no change, or makes an irrelevant change. For new containers, escalate to chat.
### Chat
Chat is the full-regeneration surface. Any structural change, aesthetic pivot, multi-component change, or new section requires a chat turn. The artifact regenerates against the new prompt; previous Tweak panel and comment state may not survive intact.
Chat costs one full turn — count it against the session budget. Use the layer-1-through-5 framework (`references/01-prompt-fundamentals.md`) for the chat prompt rather than free-form natural language.
### Per-operation surgical-vs-regen catalogue
A practical lookup for which surface fits which operation (synthesized from `research/04`):
| Operation | Surface | Notes |
|-----------|---------|-------|
| Section reordering | Tweak | Pre-derived if Claude includes a section-order control |
| Variant swap (component variant A → B) | Tweak | If Claude generated multiple variants |
| Density slider (compact / cozy / comfortable) | Tweak | Common Tweak control |
| Spacing scale (--space-* token shift) | Tweak | Common Tweak control |
| Color temperature (warmer / cooler) | Tweak | If Claude derives this dimension |
| Typography scale (modular scale shift) | Tweak | If Claude derives this dimension |
| Padding / radius / shadow per component | Tweak | Common Tweak controls |
| Text edit in existing component | Comment | Surgical, in-component |
| Color tweak in existing component | Comment | Surgical, in-component |
| Add a new section | Chat | Structural — Tweak / Comment cannot do this |
| Aesthetic pivot (industrial → editorial) | Chat | Full regen — name the new aesthetic |
| Multi-component change (revise hero + CTA + footer together) | Chat | Full regen — too broad for Comment |
| New interaction state (hover / disabled / active) | Chat | Structural — requires regeneration |
---
## 2. Anthropic-published surgical/structural split
Anthropic's verbatim framing in `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`: the Claude Design canvas distinguishes between *surgical edits* (per-element changes that do not regenerate the artifact) and *structural edits* (new components, new layouts, aesthetic pivots that require regeneration). The Tweak panel and inline comments are surgical surfaces; chat is the structural surface.
The operator's job is to identify which kind of edit a given change is *before* picking the surface. A surgical change attempted via chat regenerates the whole artifact and burns a turn; a structural change attempted via comment fails silently and wastes time. Misclassification is the dominant inefficiency in a long Claude Design session.
Source: `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`.
---
## 3. Anthropic-engineering refine-vs-pivot rule
Anthropic publishes a verbatim refine-vs-pivot guideline in `https://anthropic.com/engineering/harness-design-long-running-apps`:
> Pivot to an entirely different aesthetic if the approach wasn't working — iteration within a bad direction compounds the failure.
The companion warning, also verbatim from the same source: design quality is **non-monotonic** across iterations. Turn 4 can be worse than turn 3 on a critical criterion. The framing matters because the operator's intuition pushes toward continued refinement; the discipline is to recognize a stuck state and pivot.
Operational signal that a pivot is needed (community-converged from `research/04`):
- Three consecutive comments have failed to land
- The aesthetic is drifting back to the AI-slop default on each regeneration
- The operator finds themselves explaining what they *don't* want more than what they *do* want
- The artifact is converging on a different audience than the brief
Pivot move: rewrite the layer-2 aesthetic-family specification entirely, then ship a fresh chat turn against the new family. Do not try to incrementally edit out of a stuck state.
Source: `https://anthropic.com/engineering/harness-design-long-running-apps`.
---
## 4. Session-management heuristics
Four heuristics — one Anthropic-published, three community-converged — govern when to break a session.
### 4-screen inflection (community-converged)
Practitioners across multiple posts in `research/04` document a quality inflection around the fourth screen of context in a Claude Design session. Before screen four, edits land cleanly; after, comments start vanishing, aesthetic defaults creep back, and Tweak controls feel less precise. The exact mechanism is unclear (context-window pressure on Opus 4.7 + cumulative DESIGN.md re-reads + cumulative artifact history), but the pattern is consistent.
Practitioner mantra: **at screen four, save what you have and start a new session.**
### Opus 4.7 context degradation (Anthropic-published)
`https://anthropic.com/engineering/harness-design-long-running-apps` publishes the verbatim observation: Opus 4.7 quality degrades noticeably at the 40-50% context-window mark. Claude Design sessions accumulate context faster than chat sessions (each generation includes the artifact in context for subsequent turns); the 40-50% mark arrives sooner.
### Quota burn (community-observed)
Practitioner walkthroughs cited in `research/04` report quota burn rates as of 2026-04-28 per MindStudio's documented walkthrough — these are community observations, not Anthropic-published limits and may shift:
- **Pro plan:** ~25-30 minutes of active design before quota becomes the binding constraint
- **Max plan:** ~60-90 minutes of active design before quota becomes the binding constraint
These numbers assume continuous active design (chat turns, regenerations, image-form DESIGN.md anchors). Tweak panel and comment surface usage does not burn quota.
Captured-on date: 2026-04-28 per `research/04`. Not an Anthropic-published limit.
### Session-break triggers (community-converged)
Three signals that a session has reached its productive end:
- Reorder / density Tweak controls stop landing (the model is not respecting the surgical surface)
- Chat re-introduces previously-removed defaults (the model is losing the negative constraints)
- The operator finds themselves repeating the same constraint in three consecutive turns
When two of three trigger together, break the session.
---
## 5. Context-reset prompt
When the operator needs to break a session but does not want to lose what worked, the verbatim community pattern from MindStudio (2026-04-28, cited in `research/04`):
```
Before we continue, summarize the design system and component decisions
we've made in this session as a structured markdown document I can use
as a fresh starting context. Include:
- the aesthetic family we converged on
- color palette in CSS-variable form
- typography decisions (typeface, modular scale, weights)
- component patterns we settled on
- decisions we made and then reversed (so I don't reintroduce them)
- anything we tried that did not work
```
Paste the produced markdown into a new Claude Design session as the opening context, alongside the original DESIGN.md. The new session starts with the cumulative decisions but a fresh context window.
Captured-on date: 2026-04-28.
---
## 6. Recovery prompt library
Five recovery moves, listed in escalating cost order.
### 6.1 — Break the default aesthetic
The highest-leverage single content asset in this plugin. Adapted with attribution from `https://github.com/rohitg00/awesome-claude-design/blob/main/prompts/break-default-aesthetic.md`. Use when the artifact has drifted toward AI-slop defaults despite negative constraints in the brief.
```
The current direction has converged on a generic default. I want a
distinct visual direction. Constraints:
1. Pick ONE aesthetic family and commit to it. Name a concrete reference
(an existing product, an editorial source, a design movement). No
"modern SaaS", no "clean", no "minimal" as the named family — those
are defaults, not directions.
2. Do not produce any of:
- Inter, Roboto, Arial, Space Grotesk as primary typeface
- Purple gradients on white backgrounds
- Three-column feature grids with icon + headline + line
- Centered-hero-with-single-CTA layout default
- Glassmorphism, neumorphism, generic "modern" defaults
3. Before generating: list four candidate directions matching the goal
and audience. For each:
- Aesthetic family (with concrete reference)
- Color palette in hex
- Typeface (named)
- One-line rationale tying it to goal + audience
Wait for me to pick one. Do NOT default to "the most common modern
approach."
4. The aesthetic should surprise without being weird. If you're tempted
to write "professional" or "balanced" or "approachable", stop.
Those words signal default-mode reasoning.
```
### 6.2 — Fix the system, not the prompt
Community pattern: when iteration is stuck, the prompt is rarely the problem. The DESIGN.md is. Reopen the DESIGN.md, audit the section the artifact is drifting on (typography, color, components), tighten that section, re-upload, then re-generate.
The instinct is to add more constraints to the chat prompt. The discipline is to fix the upstream anchor.
### 6.3 — Edit previous message rather than send a new one
Community-documented workaround for context-bloat: when the previous prompt almost worked but missed one detail, edit the previous message rather than send a new turn. Claude Design re-generates from the edited message without adding to context. This is in `research/04` as a low-cost recovery move for the case where a single-word change would have fixed the output.
### 6.4 — 3-failed-comment escalation rule
If three consecutive inline comments fail to land, stop commenting and escalate to chat. The comment surface is signaling that the model is not in a state to respect surgical edits — either the artifact has drifted too far from the brief, the context window is pressured, or the change is actually structural and was misclassified.
Escalation move: paste the failed comment text directly into a chat turn, prefaced with "the inline comment surface is not landing on this; please apply this change via regeneration".
### 6.5 — Model downshift escalator
When Opus 4.7 generations are non-monotonic in quality and Tweak / Comment / chat moves all stop landing, the recovery move is to start a fresh session at a different model. The downshift sequence community-converged on (per `research/04`):
- Opus 4.7 → Opus 4.6 (same family, less context-pressure-sensitive)
- Opus 4.6 → Sonnet 4.6 (faster, less context-sensitive, sometimes better at constraint-following on tight briefs)
Claude Design pins to Opus 4.7. The downshift happens by moving the work to a different Anthropic surface (Claude.com chat with a model picker) for the constraint-tightening turn, then bringing the result back to Claude Design as a new session anchor.
### 6.6 — Verbal save-pattern
When the operator wants to preserve what works but try a different direction without losing the current state, the community pattern is to **verbally save** in chat:
```
Save what we have. The current direction is good but I want to explore
a completely different aesthetic for comparison. Acknowledge this save,
then start fresh on a new direction without referencing the saved state.
We may come back to it.
```
The "save" is verbal — Claude Design has no version-tree primitive — but it signals to the model that the previous direction is preserved in the operator's mental model and the next turn is exploratory.
---
## 7. What Claude Design lacks
Four primitives that exist in adjacent Anthropic surfaces but not in Claude Design today. The plugin must never promise these:
- **No `/rewind`** — Anthropic Code has a `/rewind` primitive that reverts to a prior conversational state. Claude Design does not.
- **No version history** — there is no Tweak-history, no Comment-history, no chat-thread-fork primitive. The verbal save-pattern (Section 6.6) is the closest substitute.
- **No two-way handoff** — once an artifact is exported to Claude Code, there is no path back into Claude Design. Re-import requires a screenshot → new Claude Design session (lossy). See `references/04-handoff-and-scope.md`.
- **No branching** — Claude Design cannot fork a session into parallel directions and compare. The verbal save-pattern is the only branching primitive.
When the operator asks for any of these, name the constraint and offer the closest substitute (verbal save-pattern, multi-session-with-context-reset-prompt, manual screenshot archive).
---
## Sources
- `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` — surgical / structural edit split, intent presets
- `https://anthropic.com/engineering/harness-design-long-running-apps` — refine-vs-pivot rule, non-monotonic improvement, 40-50% context degradation, design grading criteria
- `https://github.com/rohitg00/awesome-claude-design` — community recovery prompts, break-default-aesthetic source
- `https://claude.com/blog/improving-frontend-design-through-skills` — AI-slop avoid-list applied during recovery
Re-research trigger: Anthropic publishing version-history or branching primitives; community 4-screen inflection no longer reproducing; quota mechanics shifting (Pro / Max minute counts have a 2026-04-28 captured-on date and are community-observed, not Anthropic-published).