UI Design Phase Flow Grill Status

Source: user request to design a route-gated skill phase for frontend design discovery, proposal, prototype, backlog, and delivery handoff.

Branch Dashboard

Parked Branches

• None yet.

Glossary

Terms

• Route-gated skill: A skill that reads durable evidence, selects one next phase, loads only that phase instructions, writes handoff state, then stops or re-enters. Avoid: eager wrapper graph, front-loaded design chain.
• Design phase: A route-gated skill phase for existing design intake, design grilling, proposal/prototype iteration, backlog conversion, and delivery handoff. Avoid: ui-design-phase, frontend-design-phase, product-design-phase, design-discovery-phase, visual-design-phase.
• Design evidence intake: The phase that reads existing product visual context before any user grilling or new proposal generation. Avoid: moodboarding first, blank-slate design start.
• Low-confidence intake: Intake state where too little existing design evidence exists to safely prototype without one concrete user clarification or screenshot. Avoid: silent blank-slate assumption.
• Design grill: Requirements grilling scoped to visual, UX, content, interaction, and section/page decisions. Avoid: ad hoc preference chat.
• User-visible scope unit: A page or flow that users experience as one coherent design decision surface. Avoid: default section-by-section interrogation.
• Prototype phase: The phase that generates design directions and immediately turns them into the user-requested image reference or prototype artifact. Avoid: standalone proposal phase.
• Artifact intent: The user-selected target artifact type for prototype work, either image references or prototype artifacts. Avoid: capability-driven output choice.
• Approved artifact set: The design artifacts for one user-visible scope unit that the user has explicitly accepted for backlog conversion. Avoid: implied approval, assumed design lock.
• Artifact contract: The required context bundle for an approved artifact set before backlog conversion. Avoid: prose-only design memory.
• Delivery handoff: The design-phase phase that activates delivery-phase with backlog scope, approved artifact links, target surfaces, required frontend skills, and validation expectations. Avoid: recommendation-only closeout.
• Prerequisite evidence: The artifacts or state a direct phase entry must verify before executing that phase. Avoid: phase jump by assertion.
• Router output contract: The required router decision shape: selected phase, evidence, next file, stop-or-reenter decision, and blockers. Avoid: implicit routing.
• Phase handoff contract: The required phase completion shape: phase, status, artifacts, validation, open questions, and next recommended route. Avoid: transcript-only resume state.
• Route invariants: The non-negotiable laws for a route-gated skill runtime. Avoid: best-effort routing.
• Staleness rules: Criteria that let the router reject existing artifacts as invalid or outdated. Avoid: treating artifact existence as artifact validity.
• Phase delegation rules: Phase-local limits on which child skills may be activated after the router selects that phase. Avoid: eager child-skill activation from the entrypoint.
• Route trace: A compact decision log recording each router transition and the evidence that selected it. Avoid: unaudited phase transition.
• Repo asset manager: The persisted repository setting that tells design, backlog, delivery, and PR flows where durable visual assets are hosted. Avoid: ad hoc screenshot storage.
• Repo settings: The .devpunks/settings.json file that stores repository-level Harness configuration such as backlog provider and asset manager. Avoid: scattered provider pins.
• Backlog provider: The configured backlog system slug used by planning and backlog-writing flows. Avoid: inferred wiki provider.
• Asset provider slug: The configured provider slug used to choose durable asset upload behavior. Avoid: implicit host guess.
• Repository manager: The configured repository hosting provider whose CLI can manage repo-owned assets and PR evidence. Avoid: untracked repo host assumption.
• Repo asset management skill: The internal skill that exposes concise asset-hosting rules and provider-specific CLI references for durable visual evidence. Avoid: duplicated provider command prose in phase skills.
• Backlog attachment: A durable asset attached to the backlog provider item and linked from the backlog body. Avoid: prose-only backlog evidence.
• Repo-provider attachment: A durable asset hosted by the repository manager when backlog attachments are unavailable or unsuitable. Avoid: temp file fallback.
• Required scaffold tool: A CLI required by repo settings and checked during scaffold/update validation. Avoid: optional provider-only side list.
• Visual evidence asset: A durable hosted image or prototype screenshot linked from backlog, implementation notes, or PR context. Avoid: local temp screenshot, ephemeral browser URL.
• Design artifact: An approved visual source of truth that implementation can inspect later, including generated images, prototype URLs/files, screenshots, component notes, tokens, and decision records. Avoid: vibe, inspiration only.

Relationships

• Design phase uses Route-gated skill semantics.
• Design phase routes web and mobile surfaces through the same outer lifecycle.
• Design evidence intake must precede Design grill unless the user explicitly starts from a blank slate.
• Low-confidence intake occurs when fewer than routes plus at least one style, component, or content source are available.
• Design grill produces accepted constraints consumed by Prototype phase.
• Design grill defaults to one branch per User-visible scope unit.
• Prototype phase consumes Design grill constraints and produces approval-ready artifacts.
• Artifact intent selects the primary output path; runtime capability only controls image-to-prototype fallback.
• Approved artifact set belongs to exactly one User-visible scope unit.
• Artifact contract belongs to each Approved artifact set.
• Design artifact becomes backlog context through write-backlog.
• Delivery handoff activates delivery-phase.
• Direct phase entry requires Prerequisite evidence.
• Router output contract precedes every selected phase.
• Phase handoff contract follows every completed phase.
• Route trace records every phase transition.
• Repo asset manager is consumed by design-phase, write-backlog, implement-spec, and delivery-phase.
• Repo settings owns backlog provider and asset manager selection.
• Repo settings records Backlog provider, Asset provider slug, Repository manager, and Mandatory scaffold CLI requirements.
• Repo asset management skill owns provider-specific asset upload guidance referenced by design-phase, write-backlog, implement-spec, and delivery-phase.
• Backlog attachment is preferred for approved design/prototype assets when the backlog provider supports attachments.
• Repo-provider attachment is used when Backlog attachment is unavailable.
• Visual evidence asset belongs to an approved artifact set, backlog item, implementation note, or PR evidence section.

Axioms

• Existing design system evidence is product truth; new taste rules adapt to it instead of replacing it silently.
• Missing Figma or screenshots do not block intake by default; absence is recorded as evidence quality.
• Web and mobile differ at proposal/prototype generation, not at the outer phase lifecycle.
• Design grilling decides constraints and intent; prototype work discovers detailed UI direction.
• Section-level grill branches are exceptional and only exist when the section has independent conversion, product, or interaction meaning.
• Design directions do not live as a standalone phase; they are prototype input.
• Image generation capability is detected only after artifact intent is known.
• Imagegen unavailability can fall back to prototype artifacts; prototype requests do not fall back to image generation.
• Prototype work is delegated away from the main orchestration thread so the main thread stays clean for user discussion and validation.
• If the user asks for image references and image generation is unavailable, the phase falls back to prototype artifacts instead of blocking.
• No approved artifact set means no backlog conversion for that user-visible scope unit.
• Approved artifact sets must include enough artifact, constraint, design, implementation, and acceptance context for future implementation.
• Backlog stories from this phase must carry explicit design artifacts, not only prose.
• delivery-handoff starts delivery-phase; it does not merely recommend it.
• Direct entry into a later phase is valid only when the router verifies the same prerequisite evidence the normal route would have produced.
• The router chooses exactly one next phase and must not read sibling phase files speculatively.
• Existing artifacts are evidence, not trophies; the router must apply staleness rules before reusing them.
• A selected phase may delegate only to the child skills named by that phase.
• Long design-phase runs should leave route trace entries, especially across prototype, approval, backlog, and delivery-handoff transitions.
• Proposed design/prototype screenshots should be uploaded through the configured repo asset manager before backlog links are written.
• UI implementation PRs should include before/after visual evidence using the same configured asset manager.
• Skills must read backlog provider and asset manager settings from .devpunks/settings.json; wiki provider files can be mirrored human docs but not the authority.
• .devpunks/settings.json always has precedence over inferred repo history, wiki docs, and legacy provider files.
• If .devpunks/settings.json is missing, scaffold/update may generate it from current repo history for backward compatibility.
• dp scaffold init should prompt for repository manager selection in addition to backlog provider selection.
• Selecting a repository manager adds its CLI to the same required-tool list as other scaffold-required CLIs.
• Required scaffold CLIs should be committed in .devpunks/settings.json so existing repos gain backward-compatible CLI checks when repo manager info is added.
• Existing wiki backlog provider pages should be deleted when the settings source is implemented.
• Reusable skill changes must be authored in /Users/stefan/Desktop/repos/wearedevpunks-skills first, then synced into Harness.
• Call sites should reference the new repo asset management skill instead of duplicating provider-specific upload instructions.
• Backlog attachments are preferred for approved design/prototype assets; repo-provider attachments are the fallback when backlog attachments are not possible.
• Local temp files and committed screenshot files are not durable visual evidence by default.

Flagged Ambiguities

• "ui-design-phase" may imply only UI screens, while the proposed flow covers product-page structure, UX flows, visual design, content hierarchy, assets, and implementation handoff.
• "prototype" previously mixed generated bitmap references and prototype artifacts. Resolution: user artifact intent selects image or prototype first; capability detection only controls fallback from image to prototype when needed.
• "grill" could expand into premature design interrogation. Resolution: keep it lean and limited to constraints, goals, inventory, and hard requirements.
• "Direct entry" could sound like skipping the router. Resolution: direct entry still routes through router.md, verifies prerequisite evidence, applies staleness rules, emits the router output contract, and records a route trace.
• "Backlog provider" is currently split across wiki files in this repo. Resolution: .devpunks/settings.json becomes authoritative and the wiki backlog provider pages should be deleted.

Current Handoff

• Branch percentages: Naming 100%; Route model 100%; Intake 100%; Grill 100%; Prototype 100%; Backlog/delivery 100%; Repo asset settings 100%.
• Parked branches: none.
• Remaining non-design validation work: verify concrete schema against current scaffold/update code, implement source skills in /Users/stefan/Desktop/repos/wearedevpunks-skills, sync Harness mirrors, and run repo checks after implementation.
• Recommended next planning direction: convert closed requirements into backlog/user-story work for design-phase, repo settings, and the repo asset management skill.