refine-design

Imported from Ondoher/polylith-skills (skills/refine-design/SKILL.md). Install upstream with npx skills add Ondoher/polylith-skills --skill refine-design. Copyright stays with the author.

Refine Design

Run one bounded design-refinement cycle. Treat the user's current input as a fresh, potentially unstructured design input and reconstruct context from durable documents rather than conversation shape. Reuse product meaning and prior evidence recorded there; consult only specialists whose input can materially change the result. The workflow is planning-only, with a bounded design-language artifact path. It does not require a complete specification or a repository implementation opt-in.

Product Neutrality And Anti-Overfitting

Treat every product, repository, domain, and brand as task input rather than global policy. Never add a product name, repository path, feature concept, design choice, technology selection, exception, or evaluation shortcut to this skill, its reusable schemas, fixtures, defaults, scripts, or specialist contracts merely because that product is being used to develop or test the workflow. Keep product-specific decisions and evidence in the product's own documentation and generated artifacts. Reusable fixtures use synthetic names and content. A global change must be justified independently of the current product and remain suitable for an unrelated product.

Do not turn one product's successful pattern, failure, artifact shape, vocabulary, or evaluation case into a universal rule. Generalize only from independently justified evidence, and validate reusable rules against materially different product shapes. Preserve product-owned exceptions as product data instead of weakening a reusable contract to make one fixture pass.

Greenfield Artifact Policy

Every persisted artifact kind has exactly one current schema. Accept that exact version and reject both earlier and later versions before creating, replacing, or staging any artifact. Current versions are: product model/context 1.0, UX and UX review 0.2, UI composition and component design 0.2, design language 0.14, and review layout 7.

This skill has no migration, import, downgrade, dual-write, compatibility-reader, or compatibility-publication path. Do not preserve an obsolete schema, fixture, entrypoint, generated format, or test merely because it existed previously. Adding compatibility work requires explicit current owner authorization that names the real external consumer and its still-existing data; a hypothetical future consumer, a historical fixture, or this skill's former output is insufficient. Treat a schema change as a greenfield contract replacement unless that authorization is present.

Run npm test for routine refinement changes. It is the fast product-contract and version-policy gate. Use npm run test:design for the bounded current-design smoke after UX, UI, component, or design-language changes. Use npm run test:renderer to exercise the exhaustive renderer matrix directly, npm run test:design:full for the design smoke plus that matrix, and npm run test:full only for a deliberate release-level check. Do not run wildcard test suites as a routine precaution.

No Prerequisites

Product-name clarification is required before choosing a persistence location: if the human description does not clearly name the product and the current user has not already supplied that answer, ask for it. Continue useful read-only analysis while waiting, but never invent a name or save to a guessed folder. For repository-backed work, read the product location contract and use <repository-root>/product/<name>/ for all durable product-design data.

Start from any available description, including an empty starting point. A repository, completed brief, prior UX inventory, accepted design language, selected framework, component list or callable specialist is not a prerequisite. Reuse available context; infer a usable current design direction where the evidence supports one and expose material uncertainty. Record missing information and use disclosed rendering defaults where necessary. Ask optional questions while making useful progress; do not turn incomplete design into an entry gate.

When the named specialist is unavailable, the parent performs the assessment and records source.kind or assessment.kind parent-assessment; never claim a specialist run. Use scripts/consultation-provenance.mjs when programmatic orchestration selects the path. Tool availability limits evidence, not the user's ability to use this skill. A sparse brief still uses the current design-language schema 0.14 with empty or unresolved current fields where its contract permits them. Scope the proposal to supported evidence, render the available foundations, and add relevant components as the design evolves. Do not import unrelated fixture examples to fill a schema.

Establish Context And Scope

Resolve CODEX_HOME, falling back to ~/.codex. Specialist definitions live in the Codex root's agents/. Resolve the physical target of its documentation/ directory and use the parent as the governance root; contracts and guidance live at planning/implementation-agents/ below that governance root. Load the selected role's resources as needed, not the whole topic or every standards library. Respect applicable AGENTS.md and folder standards/overlays for files read or changed.

Use the user's supplied topic/documents or the active topic. Establish the requested question or changed decision, accepted requirements and rationale, current alternatives/open choices, and relevant existing assessments. Every concrete choice selected by a consulted agent within its assigned authority becomes the current accepted working decision when incorporated; the user does not need a separate acceptance step. This applies to product, UX, UI, system architecture, model, controller, and other planning specialties. Candidate alternatives the agent did not select, research observations, and gaps for which no usable choice was made remain non-accepted. A later human edit to product-description.md overrides any conflicting derived choice and triggers regeneration or reassessment of affected artifacts. Keep technical choices in their technical authority rather than turning them into product behavior, but reassess them when a product-description change invalidates their inputs. Do not treat obsolete reports or a scaffold as stronger authority than current owner decisions.

locked is stronger than accepted. Only a current, explicit user instruction naming the design scope may create a lock, alter locked content, update its bound source revisions, or remove the lock. A general refinement request, regeneration, new agent run, inferred improvement, changed dependency, or broad product-description edit is insufficient. Preserve locked records exactly and report any conflict or stale dependency instead of silently adapting them. An agent may recommend reconsideration, but the parent must not apply it. The parent passes --lock-reason or --locked-change-reason to the relevant persistence command only when the current user instruction supplies that authority. Whole-comp locks protect the comp and its exact UX/design-language bindings. Generated review pages visibly identify locked content; ordinary accepted content remains unmarked.

When product planning has a durable documentation folder, read the product-description contract and canonical product-model contract. Prefer its human-owned product-description.md as the root product input. Human edits are authoritative inputs. Headings, grouping, and bullets may help infer meaning, but they are not a required or stable schema. Product-description updates remain ordinary, readable Markdown.

Before any persistence, establish the product name from the description or ask the owner when it is unclear. Do not substitute the repository name, active-topic name, component name, or a generated default. Preserve the source document's existing location and resolve the repository-root data directory with scripts/product-location.mjs --repo <repository-root> --name "<name>". Use its productRoot as both the product-document root and artifact-store root for model, UX, design-language, UI, component, research, and review data; use its currentPath for artifact commits and contexts. In downstream references, <product-documentation-folder> and <product-artifact-root> mean this resolved directory, not the folder containing the description. Confirm existing store ownership before writing and follow the location contract for safe names, source bindings, existing data, and reset staging.

For every changed product description, perform one complete semantic interpretation into a schema 1.0 product-model-proposal, then run scripts/product-model.mjs with the exact source bytes. Bind an update proposal to the exact current snapshot and model. Assert stable identity for every semantic record, carry every prior record forward, and account explicitly for source claims that no longer occur in the current source. Reuse a prior ID only for continued meaning; preserve replaced meaning as a terminal superseded record. The deterministic writer assigns revisions, compares record material, records source lineage and the computed change set, commits immutable source/model/snapshot artifacts, and replaces current.json last. It does not infer semantic identity from wording similarity.

Product-model lock authority is caller input rather than proposal content. Supply a target-scoped current-owner authorization only when the current user explicitly names the locked product records to create or change. The writer persists the used authorization receipt and rejects unrelated or inferred grants. A conflict with an unchanged lock becomes an explicit unresolved gap and partial model instead of a silent lock change.

After the product model is current, read the product-artifact contract when committing UX, UI, architecture, or other structured work. scripts/product-artifact-store.mjs binds the exact current snapshot and commits an immutable artifact plus a new snapshot without accepting product Markdown or invoking the semantic parser. Current partial artifacts retain explicit gaps. Stale and locked-conflict artifacts remain auditable in the snapshot but are excluded from consumer payloads.

Do not publish a PRD from this skill and do not give downstream consumers the Markdown. Run scripts/product-context.mjs to create a deterministic, least-scope context for an authorized downstream consumer. Its canonical output is the immutable, self-contained detached context package contexts/prd/<materialSha256>/context.json with any declared files in the sibling artifact-resources/ directory under the product artifact root; copy the entire package directory when handing it off. Caller-selected mutable outputs are exports rather than refinement authority. The initial consumer is prd; its exact handoff is documented in the product-context contract. For full design publication, use the structured publication producer to validate and package current UX, design language and review layout, optional UI, repeatable component designs, and an explicit publication manifest before resolving context. The helper consumes structured sources and exact dependency IDs, never product prose. Future consumer contracts extend the resolver without introducing another prose parser.

Treat every input as if it were the first. Accept sentences, fragments, notes, or complete drafts without requiring references to the current organization. Read the entire durable product description, merge the latest human meaning, and produce a coherent newly organized description. Use supplied structure as contextual evidence, but never depend on stable headings, section order, list shape, IDs, prior prompt position, or remembered conversational structure. Preserve semantic decisions and constraints rather than document topology.

Treat design defaults as current, editable design choices. Add them to the product description and derived PRD without creating an open question or requiring explicit acceptance merely because they began as defaults. Ask about missing product behavior, material UX alternatives, or the absence of any usable design direction. Preserve provenance and affected artifacts when a default changes. Keep the PRD limited to product and UX requirements, decisions, and questions. Route schemas, APIs, persistence mechanisms, data representations, technology feasibility, and other implementation or architecture questions to engineering design review instead of surfacing them in the PRD.

The product description may explicitly request UX advice for a complex interaction that is still undefined. Treat that request as a valid product-planning task rather than as a prerequisite failure. Consult ux-planner when available. The planner performs bounded research before inventing an unfamiliar or product-specific interaction pattern, favoring primary research, original-author guidance, platform documentation, and standards over unsourced summaries. It may also investigate a material uncertainty on its own initiative while staying within its assigned scope and following the shared implementation-agent research guidance. Record candidate patterns, applicability, tradeoffs, evidence limits, the selected adaptation, and the few choices that remain unresolved. The parent source-checks material evidence before accepting a researched or novel pattern. When UX selects a supported interaction, treat it as the accepted working behavior and incorporate it into the product description. Keep a question open only when the planner cannot responsibly choose, a dependency prevents a usable recommendation, or the user explicitly defers the choice. Research findings and technical choices do not independently define product behavior; selected technical recommendations are accepted only within their technical authority.

If scope is broad, select a consequential bounded design question and state the focus. Ask only missing questions that materially prevent useful progress. A partial brief supports accepted working UX/UI recommendations where a responsible direction is available; dependent work remains conditional only on unresolved requirements or outside dependencies. User-specified budgets, agents and scope take precedence over defaults.

Choose The Planning Focus

Use two scopes within the same iterative skill. The user can say $refine-design product: ... or $refine-design architecture: ...; these are natural-language examples, not a required command parser. Infer an evident scope and state it briefly. A broad early product brief defaults to product planning. Ask only when the distinction materially changes the work and intent remains unclear.

Product planning must not drift into schemas, services or technical decomposition merely because specialists are available. Architecture planning must not silently decide product behavior or reopen accepted UX. Domain meanings and visible effects can be product decisions even when the model agent helps clarify them; classify by the decision, not the consulted role.

Cross-scope consultation is allowed for a bounded question and must return the implication to the owning scope. For example, product planning may ask whether export can survive leaving a screen; architecture planning asks the owner whether survival is required before assuming it. A mixed request may cover both, but label the product decisions and architecture recommendations separately and preserve their dependencies; do not automatically run both passes.

Handoff from product to architecture contains accepted requirements, representative workflows, relevant UI constraints, acceptance criteria and unresolved choices. Architecture returns feasibility limits and concrete alternatives when product intent needs reconsideration. Neither scope requires the entire other scope to be complete. The architecture scope remains advisory planning, not the combined coding-architecture integration test, and does not waive its opt-in/readiness gates.

UX Design Mode

For a product/UX request, read the UX design workflow and its exact schema 0.2 machine contract. Supply both to the named planner; the JSON contract is authoritative for field names, required members, arrays versus objects, enums, and conditional members. This mode turns the complete human-owned product description into a bounded application map, feature workflows, functional surface arrangements, a structured UX-to-UI handoff, and the generated PRD. It supports incomplete products and may refine one feature while preserving explicit gaps elsewhere.

UX owns product-feature organization, activity areas, journeys, entry and exit behavior, semantic regions and task order, required capabilities, actions, interaction frames, states, visible feedback, cancellation, recovery, and pruning redundant interaction. UI owns exact geometry, spacing, typography, colors, visual hierarchy and rendered compositions. A surface's functional arrangement may therefore specify its regions, ordering, persistence, action priority and focus intent without choosing pixel layout or framework components. UX publishes restrained semantic grayscale wireframes from the accepted frame/action model so the interaction architecture can be reviewed without implying UI geometry or styling.

When available, the named ux-planner returns the bounded schema 0.2 JSON design as text. The parent reconciles it with owner decisions, source-checks required pattern research, records the planner's selected recommendations as accepted working UX, then runs scripts/ux-design.mjs to validate references and persist ux/ux-spec.json in the supplied product-documentation folder. Every accepted or locked primary task must have one accepted or locked pruning review that covers its canonical steps and actions before persistence. When the named planner is unavailable, the parent may construct the same design with honest parent-assessment provenance and the same acceptance rule. Do not claim a specialist run. Repersist from the saved JSON and require byte-identical structured output before completing a slice. Publish the human review through the static HTML PRD.

After persistence, run a fresh ux-reviewer using the UX review gate. Supply the closed review schema 0.2 as a mandatory input and require the reviewer to self-check both its exact shape and every x-semanticRules entry before returning JSON. The reviewer independently assesses product intent, task coherence, action economy, state/recovery clarity, research, accessibility baseline, the UX/UI boundary, and handoff traceability. Compute and supply the receipt subject from the exact product-description file, exact saved UX bytes, requested scope, and an explicit canonical source root; the selected UX source path and supplied product path must resolve to the same real file below that root. Validate the returned receipt with scripts/ux-review.mjs against those same authoritative inputs. Route a revise verdict back through UX synthesis, validation, persistence, and a fresh review. UI design may begin only from a validated pass bound to both content hashes, their identities and revisions, and the requested scope. If the reviewer is unavailable, continue useful product and UX work but leave dependent UI work gated; a parent-authored fallback is not an independent review.

The generated PRD is organized breadth-first from the whole application to its deepest current details. Begin with application organization: shell anatomy in top-to-bottom order, navigation model, workspace, and the complete activity-area map. Then present every product capability at the same level, every work surface and its functional arrangement, accepted action/interaction-frame behavior, semantic inline wireframes, every workflow, component behavior, and finally one consolidated product-and-UX open-question section. Place each grayscale wireframe inside its owning surface after the functional arrangement and state description and before any detailed UI comp. Do not finish one feature's surfaces, workflows, and components before introducing its peer features. For a whole-product refinement, do not silently turn a multi-area description into a single-feature slice: every accepted activity area needs at least one accepted surface and goal-oriented workflow when the description supports a responsible working choice, or an explicit visible product/UX gap explaining why it remains undesigned. Keep a concise product orientation in the page header and link the design language separately. Preserve stable IDs and statuses across reorganizations. Assign acceptance during UX synthesis; rendering only preserves that decision and never changes status. Bring accepted behavior back into product-description.md in ordinary language before it governs code generation. A technical uncertainty may motivate an engineering handoff, but it does not appear in the PRD as a question or unresolved UX record. Preserve the observable product requirement and let engineering design determine how to satisfy it.

UI Composition And Product Comps

For an explicit surface or complex-component comp request, read the UI composition and HTML contract. Begin only after the exact UX schema 0.2 revision and requested scope pass the independent UX review gate. The named ui-designer may then return its JSON-only schema 0.2 composition response. The parent passes the saved review receipt, current product-description path, and canonical source root to scripts/ui-composition.mjs; persistence fails when the receipt is missing, stale, non-passing, outside the UI's consumed UX scope, or bound to a different file than the selected UX source path. When image assets are declared, pass an explicit asset root inside that canonical source root after realpath resolution; asset-free proposals do not treat their staging directory as asset authority. Generated HTML uses the same asset boundary. After persistence, render clean and annotated HTML from the same scene with scripts/ui-composition-html.mjs or the combined PRD publisher.

Bind scenes to exact UX and design-language revisions. Each scene binds one accepted interaction frame; each behavioral component node binds the exact UX interaction node and action it presents. Every frame affordance appears exactly once or is listed as deferred in a scene explicitly marked partial; complete scenes permit no deferrals. Preserve UX behavior, stable scene/node identities, Grid/Flex hierarchy, semantic template contracts, visible states, placeholders, completeness, locks, and paired HTML render requests. UI may propose a behavior change only through an explicit open uxChangeRequests record; a request does not authorize the UI to render the new or changed behavior. Route it back through UX and the review gate before binding it. Ordinary templates use semantic HTML; specialized product components remain dimensioned labeled placeholders until their dedicated comp is designed. A whole-product UI pass needs at least one representative scene for every sufficiently defined accepted surface, plus additional scenes for materially different states or transient surfaces that cannot be assessed from the representative scene. A scene with any unresolved placeholder at publication is a partial wireframe, regardless of how polished its other regions are; label it that way and never present it as a finished comp. A source scene may retain placeholder bindings for independently designed components: when every placeholder is replaced by a source-checked comp during deterministic publication, classify the published result from the resolved output rather than the source's earlier partial state. The parent owns persistence, deterministic rendering, inline illustrations in the owning UX surface, full-size clean/annotated links, browser inspection, and diagnostics. Emit the inline illustration and resolved complex components as native markup from the same structured scenes; do not use iframes in the PRD because the composition must participate in normal document flow. Do not claim a named UI-designer run when the parent authored the scene.

For a dedicated complex component, also read the complex component contract and assign the UI designer explicit component mode. For unfamiliar or product-specific controls, the lack of an immediate reference triggers bounded research using current primary product/platform sources. The designer records its search method and queries, source types and access dates, pattern comparison, and evidence limits. A shared-pattern claim requires two independent products unless a normative standard or platform guideline directly governs the component. The designer returns parent verification as pending. The parent opens the material sources, checks that they are primary and support the recorded observations, and records the source-check result before persistence. The response reuses schema 0.2 scenes with designMode: "component", including interaction-frame/node/action traceability and explicit UX change requests, explicitly classifies the artifact as a comp or wireframe, records fidelity evidence, defines a versioned componentTemplate contract, complete state-to-scene mappings, accessibility intent, and promotion metadata. The parent validates through scripts/component-design.mjs, renders focused state artifacts through scripts/component-design-html.mjs, and may register exact placeholder template IDs/versions with the combined PRD publisher only when each result qualifies as a source-verified comp. Replacement must retain the owning surface node, placement, constraints and identity; wireframes and unmatched placeholders stay visible as incomplete. A shared-candidate may produce a review-only handoff through buildComponentPromotionCandidate; applying it requires explicit user direction and a separate repository workflow. Component selection is accepted working UI by inclusion, subject to later human changes in the product description or owning design source.

Design-Language Mode

For a product/design-language request, read the current design-language contract. This path supports an optional zero-to-three-color app identity palette separated from supporting theme colors, one application theme with direct palette-member references, bounded typography, reusable component-icon rules and examples from MUI, contained/outlined/text/icon-only button states with bounded derived colors, ordinary text-field states, a bounded checkbox-group composite, and a single-selection select sharing one input-guidance/feedback pattern. The design language is a reusable application-wide system: include foundations, ordinary components, and broadly reusable patterns only. Route product-specific surfaces, non-standard components, and app-action icons to product comps, even when the current renderer has no template for them. Each product comp owns the icon meaning, visible label, state, and asset choice needed by that surface or component. Persist current schema 0.14 only. For MUI apps, use the linked MUI baseline workflow to source ordinary colors from the target version and preserve app overrides. It can start from a partial brief. Existing planning paths remain unchanged.

The named ui-designer returns the bounded JSON proposal as text. The parent may run this skill's scripts/design-language.mjs to validate and persist the current schema 0.14 artifact. Before translating qualitative owner language into exact values, apply the repeatable normalization rules; shared presets outrank agent taste, and uncovered ambiguity remains explicit. For a completed first pass, follow the completion and verification procedure in the design-language contract: derive examples from actual product capabilities, distinguish generic catalog evidence from product requirements, check icon semantics, replay the render with scripts/design-language-verify.mjs, and inspect representative output when a viewer is available. This narrow permission covers local design-artifact generation and temporary staging only; it does not authorize application implementation, installation, configuration changes or external publication. Follow the linked ownership/conflict rules and identify fixture versus specialist evidence. If no relevant value changed, reuse the saved proposal without another consultation.

For the selected static-HTML review path, a saved schema 0.14 design language can be published without another UI consultation by running node scripts/design-language-html.mjs <design-language.json> <prd-output-root> [--layout <review-layout.json>] [--title <title>] [--source-label <label>] [--layout-label <label>]. The publisher uses the sibling review-layout.json by default, validates both structured sources, emits the standalone design-language/index.html, shared assets/prd.css, local font assets and render-report.json, and refuses unowned output or linked destinations. The page includes the standard-component inventory, representative control layouts, reusable component-internal icons, and redlines sourced from maintained metrics. Published design content is accepted working design by inclusion, so cards do not repeat accepted/proposed/default status pills; explicitly identify only unselected alternatives, missing requirements, and unresolved questions in their appropriate comparison or gaps material. It excludes product-specific component gaps, app-action icons, and product workflow questions; those belong to product comps and the PRD. Each redline is a marker anchored inside the measured padding, gap, or control wrapper. Its metric class references the same CSS variable that creates that layout dimension; pseudo-elements draw the capped line and adjacent generated label, and the marker box highlights the measured span. Use translucent marker and label backgrounds so underlying component detail remains visible. Use the shared metric registry and placement vocabulary rather than detached legends or template-specific lengths. Detailed component states belong to the linked component catalog rather than this page. Treat this HTML as generated review output: return decisions through the structured design or review-layout source and regenerate. Require a byte-stable repeat publication, run scripts/design-language-html.test.mjs, and inspect the complete page in a local browser. This HTML path replaces new Markdown/SVG publication work; SVG remains an inline asset representation for bundled icon geometry.

For final PRD publication, use the structured publication producer to package current UX, design-language, optional UI, and component sources into a detached context under product/<name>/contexts/prd/, then hand that context to generate-prd. The static HTML rendering contract documents the underlying renderer and bounded inspection output; it is not an alternative final-publication path from this skill.

For layout consolidation, use default layout rules: representative spacing and typography, including component internals, in one layout reference. The bounded annotated dialog is a generic layout specimen, not a product-screen comp or new feature.

Consult Selectively

This skill explicitly authorizes spawning relevant available agents for read-only design consultation within the user's planning request. Use the existing named roles and their contracts; do not silently substitute another role or launch a writing mode.

The view/coding-architecture/test specialties are not guaranteed installed or authorized for this entry point. Use them only after their actual named roles and contracts explicitly support this planning path. Until then, report the relevant capability gap, return conditional parent-authored advice labeled as such when useful, and continue unaffected work. Do not install roles, use compliance reviewers as planners or run a separate CLI to evade unavailable delegation. If delegation is unavailable, say so; a parent-only analysis is not a specialist run.

Do not start every role. Zero consultations is appropriate for recording an explicit decision or reusing a still-current assessment. Begin with one focused consultation round; usually one or two roles suffice. Parallelize genuinely independent questions when worthwhile, and sequence dependent ones. At most one targeted follow-up round is the default; otherwise return unresolved choices for the next call. A user's explicit broader request can change this bound. The required fresh UX review is a serial quality gate for UI work, not an optional consensus round and not a reason to consult unrelated roles.

Route each question to the available specialist most likely to answer it from the relevant decision ownership and evidence. Start with that role instead of broadcasting the question. When a consulted specialist identifies a material question outside its scope, it returns a focused request to the parent; route that request to the best-fit role and bring the result back to the owning decision. A specialist may research facts needed within its own scope, but cross-specialty uncertainty should not be answered by guesswork. Follow planning/implementation-agents/research-guidance.md under the resolved governance root.

For each selected specialist supply: planning-consultation assessment mode; bounded question/scope and paths; accepted inputs and known constraints; changed assumptions; relevant prior findings with acceptance status; missing dependencies; and expected response. Request a concise recommendation, rationale/alternatives, contract implications, owner decisions and evidence limits. For UX-design and design-language work, request the bounded JSON response defined in the applicable workflow and machine contract instead of the default prose report. Specialists return text only; no writes, builds/tests/apps, external messages, elevation, recursive delegation or implementation. Use a fresh specialist for each bounded consultation and release it after its response. Do not retain idle agents or depend on live threads for follow-up context; assemble later inputs from durable records.

Planning consultation by model/controller is now an explicit path in their contracts. It permits advisory analysis, not full architecture integration, code task assignment, infrastructure changes or workflow activation. Coding orchestration, even report-only integration, retains its separate opt-in/readiness gates.

Synthesize And Preserve Decisions

Resolve overlaps by ownership: UX describes intended behavior, UI describes presentation, system architecture assesses capabilities, model describes domain guarantees, controller coordinates operations. A selected recommendation from any agent is the accepted working decision within that ownership boundary. Do not promote unselected alternatives or advice outside the specialist's ownership, and return consequential cross-owner conflicts to the user. Additional specialist work must answer a material question, not seek endless consensus.

For authorized documentation work, the parent updates the human-owned product description, persisted design artifacts, and relevant planning records; final PRD publication is a separate generate-prd handoff. Record every selected agent recommendation as an accepted working decision in the artifact owned by that specialty; keep unselected alternatives and genuinely unresolved gaps distinct. Preserve owner rationale; link to source evidence rather than paste entire reports into every document. Never modify application code, tests, agent configuration, canonical standards or repository opt-in through this skill. An engineering-rule conflict is a reported reconciliation need, not permission to override it in product notes. External publication/messaging and full SVG comps remain outside this version. The design-language path explicitly permits the parent to generate its bounded SVG palette, typography, icon, password-component, command-button and ordinary text-field, composite-input and single-select state specimens, button-variant comparisons and supporting documentation. Product-specific and non-standard components remain in the product-comp path.

When a consultation produces research worth reusing, the specialist includes a compact preservation handoff: question, material sources and versions/dates, findings, applicability and limitations, affected decisions, and unresolved conflicts. The read-only specialist does not persist it. The parent saves the useful evidence in the relevant authorized product, planning, architecture, or research record before releasing the agent. Do not save full transcripts or rely on agent memory as durable context.

The product description is maintained as natural-language Markdown without generated ownership markers or a rigid template. Read it semantically and re-synthesize it into the clearest current capability and UX-flow organization after each input. Preserve the human's meaning, not their incidental formatting or the previous document structure. The PRD may use richer generated formats. Incorporate accepted agent choices that affect product intent into the product description in ordinary language; retain technical decisions in their owning architecture records. For code generation, current accepted generated designs elaborate the product description, while any conflicting human-authored product-description statement takes precedence and requires regeneration before implementation continues. Unselected alternatives and unresolved records remain non-decisions.

For design-language mode, maintain the current structured source and current review pages for colors, typography, layout, components, decisions, and reusable component-internal icons. Do not add a separate planning.md. For other planning work, when repeated planning needs durable continuity, keep the decision record under the resolved product/<name>/ root and link it from the topic index. Existing topic records may supply prior context; do not silently relocate them or continue a competing canonical product-data store there. Only create or update documents when the user's task authorizes maintenance; a discussion-only request returns text. When a repository and clear product name are available, the canonical directory is determined without asking for an output folder. If the repository or name is missing, ask for that required information before persistence and continue useful unsaved analysis. No full transcript or duplicate requirements catalog is needed.

The record needs only: current planning scope and focus; changed/accepted decisions with rationale and links; open choices with affected areas; active proposals and evidence; which prior findings remain reusable or need reassessment; and the next useful question. Record consulted roles, material input versions or changes, outcome and available time/usage concisely. Never infer credits or child-only cost from wrapper totals. Durable conclusions must not depend exclusively on temporary report files.

A changed decision invalidates affected recommendations only. For example, a persistence decision can affect system/model/UX advice without reopening typography. If nothing material changed, reuse existing conclusions instead of paying for another assessment.

Evaluate Change Impact And Reproducibility

Before revising structured artifacts, compare the current and candidate decisions rather than relying on document revisions alone. Use scripts/refinement-impact.mjs when the inputs can be expressed as source records and artifact dependencies. A material change makes only artifacts that consume the changed record stale. A source revision with unchanged material content requires an exact rebind, while unrelated artifacts remain reusable. A dependency change that reaches a locked artifact is a locked-conflict: report it and preserve the artifact and its bindings until the user explicitly names that locked scope. Never treat a full republish as evidence that every decision changed; unchanged owned files should remain byte-identical.

Independent specialist runs need materially equivalent normalized designs, not identical narrative provenance. compareMaterialDesigns may ignore run assessment, source paths, research dates, query ordering, review dates, and revisions while retaining selected decisions and behavior. For independently coined UX 0.2 records, compareInteractionArchitectures also normalizes synonymous fresh IDs, prose, exact frame trees, and pruning bookkeeping that references no action. It retains canonical interaction methods and input modalities, presentation and visibility, state applicability and transitions, feedback, cancellation, recovery, selected research basis, and pruning dispositions attached to actual actions. Use that comparison as a first check, then review any difference for product or UX significance. Do not weaken the projection to hide a behavioral disagreement. A deterministic preset or saved decision must produce the same material renderer input regardless of which qualified agent performs the pass.

The reusable MVP evaluation set is: empty or sparse cold start; unchanged replay; an accepted decision change; a locked dependency conflict; partial input; honest parent-assessment fallback when a named planner is unavailable; an independently reviewed UX pass and revise case; one transient interaction frame with focus, action grouping, cancellation, focus return, and content-driven height; one researched unfamiliar pattern; primary-task pruning; action/frame-to-UI traceability; one research-backed complex component; a review-only shared-component promotion candidate; and scoped preservation of unaffected artifacts. A sample product may exercise these cases, but sample-product concepts are fixture data rather than skill requirements. The reusable evaluation record identifies the executable evidence, the fresh-agent convergence result, and the claims it intentionally excludes.

Static HTML under product/<name>/prd/ is the default maintained human-review output, published by generate-prd from a detached context. Structured UX, UI, component, and design-language JSON remain the design authorities. Existing refinement renderer helpers may emit bounded inspection artifacts; their presence does not authorize a second final PRD or an older schema. Keep saved design data and any current review artifacts beneath the named product root.

The following are deliberate post-MVP work: interactive JavaScript in generated review pages, a general responsive-breakpoint engine, application React/code generation, a complete MUI component catalog, automated screenshot baselines, automatic mutation of a shared component library, and installation of component design as a separate skill. Record a new dependency before expanding this list; do not silently imply one of these capabilities exists.

Finish The Cycle

Return what was clarified or changed, the few consequential owner decisions still needed, evidence/availability limits, any saved document links and a suggested next refinement. Stop when the scoped question is answered, owner input blocks dependent reasoning, the consultation bound is reached or evidence cannot resolve uncertainty. Do not loop waiting for hypothetical consensus or equate planning completion with implementation readiness. A later invocation resumes from the durable record and current user decisions.