UI Design Phase Flow Grill Log

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

Source Brief

The requested skill should compose existing design and frontend skills into a route-gated phase flow:

Read existing design systems before proposing changes, including theme CSS, Figma, component files, and screenshots.
Grill the user with an inner requirements-grill loop about each page, section, flow, and design decision.
Use grill artifacts to activate design-taste-frontend for design proposals.
When image generation is available, use imagegen capabilities plus imagegen-frontend-web or imagegen-frontend-mobile.
When image generation is unavailable, produce prototype skill artifacts instead, including the external prototype skill requested for addition to wearedevpunks-skills.
Delegate prototype execution to subagents so the main orchestration thread stays focused on user discussion and validation.
Iterate proposals until the current page, section, flow, or scope is fully approved.
Convert approved design scope to backlog through write-backlog, with explicit implementation-time design artifacts.
Route implementation through delivery-phase, activating design-taste-frontend and, for Codex, gpt-taste.

Open Branches

The current branch dashboard lives in ui-design-phase-flow-grill-status.md.

Branch A: Skill Naming And Scope

Q1

Question: What should the canonical skill name be for this route-gated frontend design flow?

Accepted answer:

Canonical skill id: design-phase.
design-phase covers existing design system intake, requirements grilling, proposal/prototype iteration, backlog conversion, and delivery handoff.
Rejected aliases: ui-design-phase, frontend-design-phase, product-design-phase, design-discovery-phase, visual-design-phase.
Rationale: design-phase is broad enough for UI, UX flows, visual direction, assets, prototypes, and implementation handoff without claiming all product requirements or collapsing into code-only frontend work.

Glossary Q2

Question: What term should describe the new phase wrapper?

Accepted answer:

Canonical term: 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.
Relationship: Design phase uses Route-gated skill semantics.

Q3

Question: Should mobile app design live inside the same design-phase router or in a sibling phase?

Accepted answer:

Keep web and mobile design in the same design-phase router.
Surface-specific routing happens inside the proposal/prototype phase.
Web proposal/prototype work activates imagegen-frontend-web when image generation is available.
Mobile proposal/prototype work activates imagegen-frontend-mobile when image generation is available.
The outer lifecycle remains the same: intake, grill, propose, prototype, approve, backlog, delivery handoff.
Rationale: web and mobile differ at proposal/prototype generation, not at the outer phase lifecycle.
Superseded by Q5 for phase naming: propose no longer exists as a standalone phase.

Glossary Q4

Question: What invariant should govern web and mobile scope?

Accepted answer:

Axiom: Web and mobile differ at proposal/prototype generation, not at the outer phase lifecycle.
Relationship: Design phase routes web and mobile surfaces through the same outer lifecycle.

Branch B: Route-Gated Phase Model

Q5

Question: What phase list should design-phase use?

Accepted answer:

Use phases: router, intake, grill, prototype, approval, backlog, delivery-handoff.
Do not include a standalone propose phase.
prototype generates design directions as direct input to prototype work, then immediately produces artifacts.
Rationale: design directions do not live alone; they only matter as inputs to generated images, coded prototypes, or prototype skill artifacts.

Glossary Q6

Question: How should proposal and prototype terminology be modeled?

Accepted answer:

Canonical term: Prototype phase — the phase that generates design directions and immediately turns them into inspectable visual or prototype artifacts.
Avoid: standalone proposal phase.
Axiom: Design directions do not live as a standalone phase; they are prototype input.

Branch C: Requirements Grill Integration

Q7

Question: How much should the design grill ask before prototype work?

Accepted answer:

Keep the design grill lean and concise.
Grill goals, constraints, page/section/flow inventory, existing-system conflicts, hard requirements, content ownership, platform/surface, and non-negotiables.
Do not grill detailed UI choices, visual taste minutiae, component-level design details, or decisions that can only be inspired or derived at prototype time.
Rationale: over-grilling design details creates false certainty and slows the flow before visual evidence exists.

Glossary Q8

Question: What invariant should prevent premature UI interrogation?

Accepted answer:

Axiom: Design grilling decides constraints and intent; prototype work discovers detailed UI direction.
Flagged ambiguity: "grill" could expand into premature design interrogation. Resolution: keep it lean and limited to constraints, goals, inventory, and hard requirements.

Q9

Question: What is the default grill granularity?

Accepted answer:

Default to one grill branch per user-visible page or flow.
Use a section-level branch only when the section is itself an independent decision surface, such as a hero, pricing section, checkout step, onboarding screen, or critical dashboard panel.
Avoid section-by-section grilling by default.
Rationale: page/flow branches keep the grill lean, while prototype work can discover section-level visual direction from artifacts.

Glossary Q10

Question: What term should describe default grill scope?

Accepted answer:

Canonical term: User-visible scope unit — a page or flow that users experience as one coherent design decision surface.
Avoid: default section-by-section interrogation.
Relationship: Design grill defaults to one branch per User-visible scope unit.
Axiom: Section-level grill branches are exceptional and only exist when the section has independent conversion, product, or interaction meaning.

Branch D: Existing Design System Intake

Q11

Question: What minimum evidence should intake require when Figma, screenshots, or full design-system inputs are missing?

Accepted answer:

Intake should collect available existing routes/pages or target surfaces.
Intake should inspect theme CSS, tokens, global styles, and matching component files when present.
Intake should use screenshots when available or cheap to capture.
Intake should use Figma or design files only when provided or connector-accessible.
Intake should inspect current copy/content sources and known brand/design constraints when relevant.
Missing Figma or screenshots do not block by default.
If fewer than routes plus at least one style, component, or content source exist, mark low-confidence intake and ask one concrete question or request one screenshot.
Rationale: the flow should preserve momentum while making evidence quality explicit.

Glossary Q12

Question: How should incomplete intake be named?

Accepted answer:

Canonical term: 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.
Relationship: Low-confidence intake occurs when fewer than routes plus at least one style, component, or content source are available.
Axiom: Missing Figma or screenshots do not block intake by default; absence is recorded as evidence quality.

Branch E: Prototype Loop

Q13

Question: Should code prototypes be a fallback when image generation is unavailable?

Accepted answer:

Use an artifact decision tree.
First read the user's artifact intent: image references or prototype artifacts.
If the user wants images, detect image generation capability.
If image generation is available, use the image path with imagegen-frontend-web or imagegen-frontend-mobile.
If image generation is unavailable, fall back to prototype artifacts.
If the user wants a prototype, produce prototype artifacts directly.
Do not choose images merely because imagegen exists.
Rationale: output mode is a user intent decision; runtime capability only controls fallback from image requests to prototype artifacts.

Glossary Q14

Question: What term should describe the artifact routing input?

Accepted answer:

Canonical term: Artifact intent — the user-selected target artifact type for prototype work, either image references or prototype artifacts.
Avoid: capability-driven output choice.
Relationship: Artifact intent selects the primary output path; runtime capability only controls image-to-prototype fallback.
Axiom: Image generation capability is detected only after artifact intent is known.
Axiom: Imagegen unavailability can fall back to prototype artifacts; prototype requests do not fall back to image generation.
Flagged ambiguity: "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.

Q15

Question: What is the approval gate?

Accepted answer:

Approval is per user-visible scope unit.
The user can approve, reject, or request iteration on each page or flow artifact set.
Only approved artifacts can move into backlog.
Rationale: approval must map to the same scope unit used by the lean grill so backlog conversion does not claim more design certainty than the user accepted.

Glossary Q16

Question: What term should describe approved prototype output?

Accepted answer:

Canonical term: 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.
Relationship: Approved artifact set belongs to exactly one User-visible scope unit.
Axiom: No approved artifact set means no backlog conversion for that user-visible scope unit.

Q17

Question: What must an approved artifact set contain before backlog conversion?

Accepted answer:

Scope unit name and surface: web or mobile.
Artifact intent: image references or prototype artifacts.
Artifact links and paths: generated images, prototype URLs/files, screenshots, or other inspectable outputs.
Intake evidence summary: tokens, component files, screenshots, Figma/design files, content sources, and constraints used.
Grill constraints: accepted constraints, non-goals, and parked scope only.
Design decisions: layout direction, typography, color/material, motion, imagery, and interaction states.
Implementation notes: must-preserve details, responsive expectations, accessibility constraints, and known component-system constraints.
Open or parked design questions.
Acceptance checks: what implementation must visually or functionally match.
Rationale: backlog and delivery need explicit design artifacts without turning backlog stories into implementation plans.

Glossary Q18

Question: What term should describe the required design handoff bundle?

Accepted answer:

Canonical term: Artifact contract — the required context bundle for an approved artifact set before backlog conversion.
Avoid: prose-only design memory.
Relationship: Artifact contract belongs to each Approved artifact set.
Axiom: Approved artifact sets must include enough artifact, constraint, design, implementation, and acceptance context for future implementation.

Branch F: Backlog And Delivery Bridge

Q19

Question: How should approved design artifacts move into backlog and implementation?

Accepted answer:

Backlog stories created from design-phase stay product-facing.
Backlog stories include an Implementation context link block pointing to the approved artifact set.
delivery-handoff activates delivery-phase.
The delivery-phase activation includes backlog epic/story ids, approved artifact set links, target surface paths when known, required frontend skills, and validation expectations.
Required frontend skills include design-taste-frontend; Codex also activates gpt-taste.
Validation expectations include screenshot/browser verification, responsive checks, and artifact-match checks.
Implementation can refine code, but should not renegotiate approved design unless blocked.
Rationale: write-backlog keeps body ownership product-facing while delivery-phase still receives full design truth.

Glossary Q20

Question: What term should describe the implementation bridge?

Accepted answer:

Canonical term: 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.
Relationship: Delivery handoff activates delivery-phase.
Axiom: delivery-handoff starts delivery-phase; it does not merely recommend it.

Branch G: Direct Entry Semantics

Q21

Question: Can design-phase be entered at any phase?

Accepted answer:

Yes, design-phase can be entered at any phase.
The router must verify prerequisite evidence before executing the requested phase.
Direct entry into prototype requires intake evidence plus lean grill constraints, or a recorded low-confidence intake with one concrete clarification.
Direct entry into approval requires an artifact set.
Direct entry into backlog requires an approved artifact set.
Direct entry into delivery-handoff requires backlog output plus approved artifact set links.
This follows the route-gated criteria agreed in thread 019eef69-ce40-7763-a83a-1120930ecdb4.
Rationale: direct entry preserves HITL flexibility without allowing phase jumps by assertion.

Glossary Q22

Question: What invariant should govern direct phase entry?

Accepted answer:

Canonical term: Prerequisite evidence — the artifacts or state a direct phase entry must verify before executing that phase.
Avoid: phase jump by assertion.
Relationship: Direct phase entry requires Prerequisite evidence.
Axiom: Direct entry into a later phase is valid only when the router verifies the same prerequisite evidence the normal route would have produced.

Q23

Question: Which route-gated criteria from thread 019eef69-ce40-7763-a83a-1120930ecdb4 must design-phase inherit?

Accepted answer:

Inherit the full route-gated criteria from thread 019eef69-ce40-7763-a83a-1120930ecdb4, not only a generic prerequisite check.
SKILL.md stays a thin entrypoint that explains usage and points to router.md.
router.md selects exactly one next phase from evidence.
The router must emit a router output contract: selected phase, evidence, next file, stop-or-reenter decision, and blockers.
Every phase must emit a phase handoff contract: phase, status, artifacts, validation, open questions, and next recommended route.
Route invariants apply: load only router.md first, choose exactly one phase, do not read sibling phase files speculatively, do not skip required artifacts, do not continue after a HITL stop, and after phase completion re-enter router or stop.
Staleness rules apply: existing artifacts can be invalid when they are older than source decisions, missing required scope, missing validation, stale after changed implementation, or divergent from tracker/repo evidence.
Phase delegation rules apply: a phase may activate only the child skills named by that phase after the router selects it.
Route trace applies: long runs should record transitions like router -> prototype: approved lean grill exists, no artifact set.
Examples are required in the future skill so agents can see a happy path and resume path.
Rationale: the earlier thread defined these criteria as the difference between folder organization and a runtime protocol.

Glossary Q24

Question: What route-gated protocol terms should design-phase carry forward?

Accepted answer:

Canonical term: Router output contract — the required router decision shape: selected phase, evidence, next file, stop-or-reenter decision, and blockers.
Canonical term: Phase handoff contract — the required phase completion shape: phase, status, artifacts, validation, open questions, and next recommended route.
Canonical term: Route invariants — the non-negotiable laws for a route-gated skill runtime.
Canonical term: Staleness rules — criteria that let the router reject existing artifacts as invalid or outdated.
Canonical term: Phase delegation rules — phase-local limits on which child skills may be activated after the router selects that phase.
Canonical term: Route trace — a compact decision log recording each router transition and the evidence that selected it.
Avoid: implicit routing, transcript-only resume state, best-effort routing, treating artifact existence as artifact validity, eager child-skill activation from the entrypoint, unaudited phase transition.
Relationship: Router output contract precedes every selected phase.
Relationship: Phase handoff contract follows every completed phase.
Relationship: Route trace records every phase transition.
Axiom: The router chooses exactly one next phase and must not read sibling phase files speculatively.
Axiom: Existing artifacts are evidence, not trophies; the router must apply staleness rules before reusing them.
Axiom: A selected phase may delegate only to the child skills named by that phase.

Q25

Question: How should direct entry interact with the route-gated protocol?

Accepted answer:

Direct entry does not bypass the router.
Direct entry still loads router.md, verifies prerequisite evidence, applies staleness rules, emits the router output contract, and records a route trace.
If direct entry lacks valid evidence, the router must route to the missing prerequisite phase or stop with a blocker.
Rationale: direct entry preserves HITL flexibility without weakening runtime discipline.

Branch H: Repo Asset Settings And Visual Evidence

Q26

Question: What new requirement must design-phase add for graphical assets and PR evidence?

Accepted answer:

design-phase must take advantage of the existing Harness UI screenshot evidence capability from implement-spec.
Proposed design images and prototype screenshots should be persisted as durable provider assets before they are inserted into backlog items.
UI implementation should include before/after images in PRs.
The repo needs a structured asset management setting so design, backlog, implementation, and PR handoff use the same hosting service.
Candidate source of truth: .devpunks/settings.json.
Existing provider settings such as backlog provider selection should also be candidates for this repo settings file.
write-backlog guidance inside design-phase must include links to graphical assets from approved artifact sets.
delivery-phase activation from design-phase must include explicit guidance to populate the resulting PR with before/after images.
Rationale: visual design work needs durable reviewable assets, not local screenshots or prose-only links.

Glossary Q27

Question: What terms should govern design and implementation visual assets?

Accepted answer:

Canonical term: Repo asset manager — the persisted repository setting that tells design, backlog, delivery, and PR flows where durable visual assets are hosted.
Canonical term: Visual evidence asset — a durable hosted image or prototype screenshot linked from backlog, implementation notes, or PR context.
Avoid: ad hoc screenshot storage, local temp screenshot, ephemeral browser URL.
Relationship: Repo asset manager is consumed by design-phase, write-backlog, implement-spec, and delivery-phase.
Relationship: Visual evidence asset belongs to an approved artifact set, backlog item, implementation note, or PR evidence section.
Axiom: Proposed design/prototype screenshots should be uploaded through the configured repo asset manager before backlog links are written.
Axiom: UI implementation PRs should include before/after visual evidence using the same configured asset manager.
Flagged ambiguity: "Backlog provider" is currently split across wiki files in this repo. Superseded by Q30-Q32: .devpunks/settings.json is authoritative, and wiki backlog provider pages should be deleted.

Q28

Question: Should .devpunks/settings.json become the canonical repo settings source for both backlog provider and asset manager?

Accepted answer:

Yes.
.devpunks/settings.json is the canonical repo settings source for backlog provider and asset manager selection.
Initial target shape:

{
  "backlog": {
    "provider": "linear"
  },
  "assets": {
    "provider": "github",
    "strategy": "repo-host-release-assets"
  }
}

Existing wiki provider files may become generated or mirrored human docs, but they are not the authority.
Skills that currently mention backlog provider pins or active screenshot evidence providers must be updated to read from .devpunks/settings.json.
Known call sites include docs-onboarding, write-backlog provider selection flows, create-spec and create-plan backlog sync references, implement-spec UI screenshot evidence references, and delivery-phase handoff/closeout behavior.
Rationale: provider and asset configuration should not be scattered across wiki docs and skill prose.

Glossary Q29

Question: What term should describe this repo-level source of truth?

Accepted answer:

Canonical term: Repo settings — the .devpunks/settings.json file that stores repository-level Harness configuration such as backlog provider and asset manager.
Avoid: scattered provider pins.
Relationship: Repo settings owns backlog provider and asset manager selection.
Axiom: 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.
Supersedes ambiguity: "Backlog provider" is currently split across wiki files in this repo. Further superseded by Q30-Q32: .devpunks/settings.json becomes authoritative, and wiki backlog provider pages should be deleted.

Q30

Question: What exact precedence and backward-compatibility behavior should repo settings use?

Accepted answer:

Keep both backlog provider and asset provider slug as explicit settings.
.devpunks/settings.json always has precedence when present.
If .devpunks/settings.json does not exist, Harness may generate it from current repo history for backward compatibility.
An agent updating Harness inside a repo should prefill .devpunks/settings.json instead of relying on scattered wiki/provider history.
Rationale: existing repos should keep working, but once the settings file exists there must be one authority.

Q31

Question: How should scaffold init collect and enforce repository manager settings?

Accepted answer:

dp scaffold init should prompt for repository manager selection in addition to backlog provider selection.
Selecting a repository manager makes that repository manager CLI mandatory.
The selected provider CLI should be checked through the same required-tools list as Harness default CLIs and other scaffold-required tools.
Mandatory scaffold CLIs should be committed in .devpunks/settings.json.
Adding repository manager info to existing repos should preserve backward compatibility while enabling required-tool install checks.
Examples: gh for GitHub, glab for GitLab, az for Azure, provider/API wrapper behavior for Bitbucket when no first-party CLI path exists.
Rationale: asset evidence depends on the repo host CLI, so scaffold state must make that dependency explicit and verifiable.

Q32

Question: What should happen to existing wiki backlog provider files?

Accepted answer:

Delete the wiki backlog provider pages as authoritative configuration surfaces.
Provider configuration belongs in .devpunks/settings.json.
Human docs may describe provider behavior elsewhere, but they must not compete with repo settings for authority.
Current files identified in this repo: apps/wiki/backlog-provider.md and apps/wiki/content/docs/project/backlog-provider.mdx.
Rationale: the current split between GitHub and Linear provider docs proves that wiki pages are not safe as the source of truth.

Q33

Question: How should provider-specific asset upload behavior be represented?

Accepted answer:

Create a small internal skill, tentatively repo-asset-manage or repo-asset-management.
Keep the skill concise and minimal.
Use progressive disclosure.
Put provider-specific CLI guidance under references/*.md.
Seed the provider references from /var/folders/y8/fw7tz9gn7yx645tf162zwlnr0000gp/T/repo-asset-hosting-handoff-2026-06-25.md.
Current provider guidance to preserve:
- GitHub uses gh release upload <tag> <files>... or gh release create <tag> --prerelease <files>...; no generic repo bucket exists through gh.
- GitLab prefers glab packages upload for neutral storage; glab release upload --use-package-registry only when release UX matters.
- Azure Repos has no repo-bucket equivalent; use Azure Blob Storage via az storage blob upload or az storage blob upload-batch, with Azure Artifacts or pipeline run artifacts only for package/run-scoped needs.
- Bitbucket Cloud Downloads is the repo-level bucket through REST API or the Atlassian bitbucket-upload-file pipeline pipe; no first-party generic CLI path is currently assumed.
Rationale: phase skills should call a shared capability instead of copying provider command matrices.

Q34

Question: How should source skill changes and Harness call sites be updated?

Accepted answer:

Author reusable skill changes only in /Users/stefan/Desktop/repos/wearedevpunks-skills.
Sync Harness after source changes.
Do not hand-edit Harness .agents/skills/* or apps/cli/skills/* as the source of reusable skill truth.
Call sites should mention use of the new repo asset management skill instead of embedding detailed provider CLI usage.
Affected call sites include design-phase, write-backlog, implement-spec, and delivery-phase.
Rationale: the provider behavior must stay centralized and sync-safe.

Q35

Question: Where should approved proposal/prototype assets be attached?

Accepted answer:

Prefer backlog provider attachments for proposed image/prototype screenshots.
If backlog attachments are not possible, use repo-provider attachments.
Backlog entries should link durable assets, not local temp paths.
design-phase backlog guidance should require graphical asset links in the approved artifact set and backlog implementation-context block.
Rationale: proposal artifacts belong closest to the backlog item when the backlog provider can host them; repo-hosted assets are the fallback.

Q36

Question: What should delivery-phase receive for PR visual evidence?

Accepted answer:

delivery-handoff must activate delivery-phase with explicit instructions to populate the resulting PR with before/after images.
The before/after images use the configured repo asset manager and the implement-spec UI screenshot evidence contract.
PR evidence should use durable provider-hosted links.
Local temp files and committed screenshot files are not durable visual evidence by default.
Rationale: implementation needs the same asset pipeline as design approval, and PR reviewers need durable before/after proof.

Glossary Q37

Question: What additional terms close repo settings and visual evidence behavior?

Accepted answer:

Canonical term: Backlog provider — the configured backlog system slug used by planning and backlog-writing flows.
Canonical term: Asset provider slug — the configured provider slug used to choose durable asset upload behavior.
Canonical term: Repository manager — the configured repository hosting provider whose CLI can manage repo-owned assets and PR evidence.
Canonical term: Repo asset management skill — the internal skill that exposes concise asset-hosting rules and provider-specific CLI references for durable visual evidence.
Canonical term: Backlog attachment — a durable asset attached to the backlog provider item and linked from the backlog body.
Canonical term: Repo-provider attachment — a durable asset hosted by the repository manager when backlog attachments are unavailable or unsuitable.
Canonical term: Mandatory scaffold CLI — a CLI required by repo settings and checked during scaffold/update validation.
Relationship: Repo settings records Backlog provider, Asset provider slug, Repository manager, and Mandatory scaffold CLI requirements.
Relationship: Repo asset management skill owns provider-specific asset upload guidance referenced by design-phase, write-backlog, implement-spec, and delivery-phase.
Axiom: .devpunks/settings.json always has precedence over inferred repo history, wiki docs, and legacy provider files.
Axiom: Backlog attachments are preferred for approved design/prototype assets; repo-provider attachments are the fallback when backlog attachments are not possible.

Closure

All active requirements branches are closed. Current likely next direction is backlog/user-story creation for implementing design-phase, repo settings, and the repo asset management skill.

UI Design Phase Flow Grill Log

On this page