Skip to content

feat(ux-design): add /import phase for externally built prototypes - #167

Draft
jeperry wants to merge 1 commit into
flightctl:mainfrom
jeperry:ux-design-import
Draft

jeperry wants to merge 1 commit into
flightctl:mainfrom
jeperry:ux-design-import

Conversation

@jeperry

@jeperry jeperry commented Nov 17, 2026

Copy link
Copy Markdown

Summary

Adds an /import phase to ux-design so a team can bring a prototype it already built and start at /evaluate → /handoff, without running /prototype.

The Edge/RHEM UX team prototypes in its own repository (a fork of flightctl-ui with a fixture API) well before the PRD, design doc, and [UX] story are final. When those settle, the prototype needs only small changes. Today /evaluate hard-requires 03-prototype/prototype-notes.md, which only /prototype writes, so there is no supported way in for an existing prototype.

What /import does

  • Pins the prototype to an exact commit (Git URL clone into 03-prototype/code/, or a local path's HEAD), so a moved branch can't be evaluated under an old record.
  • Runs it locally after the researcher confirms the install/start commands (repo scripts are treated as untrusted). A hosted URL is used only when it is proven to serve the same commit.
  • Captures screenshots of the feature's routes (--routes scopes a repo that holds many features).
  • When the prototype is a fork of the product UI, records unchanged / changed / mocked page sections against the upstream base and writes changeset.md.
  • Fills the existing User Stories Covered table against the PRD FR/NFRs and the [UX] story's acceptance criteria (verified / mocked / partial / deferred / missing). Deferral needs researcher approval.
  • Writes rfe-snapshot.md from the ingested story so Full evaluation works.
  • Records prototype-mode caveats (fixture API, stubbed auth, allow-all permissions) so evaluation and handoff don't overclaim.

It never edits, commits to, or pushes to the prototype repository. Fixes from /evaluate are made there, then /import runs again at the new commit.

Flow

/ingest <UX story>   # loads story + PRD + design doc in one pass (enriched)
/import --repo <url|path> --ref <branch|tag|sha> --routes /a,/b [--start "<cmd>"] [--url <hosted>] [--upstream <repo>@<sha>]
/evaluate
/handoff

The existing handoff gate is unchanged: /handoff still requires an enriched context and a confirmed evaluation bound to the current prototype iteration and context revision.

Changes

  • New: commands/import.md, skills/import.md
  • controller.md: Import phase, "bring your own prototype" flow, recommendations, phase-entry row; evaluation fix loops route to "fix in repo → /import" for imported prototypes instead of /prototype.
  • evaluate.md: accepts imported prototypes; verifies the recorded commit before evaluating; uses the recorded run command and routes; passes prototype-mode caveats to evaluators; uses the import's rfe-snapshot.md; skips refinement-input normalization (Skill prototype ID: N/A — imported); records Prototype commit in the report header.
  • prototype.md: does not refine or overwrite an imported prototype unless the researcher explicitly asks to replace it.
  • handoff.md: uses the imported code at the evaluated commit; treats fixture data as evidence of need, not API proof, and flags fields outside the generated API types as likely backend gaps; records the import in Research Context.
  • README.md, SKILL.md: documented; version 0.5.0 → 0.6.0 (new behavior).

Open questions

  • Should /import also accept a prototype with no Git history (e.g., a static export)? This draft requires Git so the evaluated artifact is reproducible.
  • Upstream drift: /import records when the prototype's upstream base is older than the discovery baseline but does not resync. Is a warning enough, or should that block evaluation?

Validation

  • skill-reviewer/scripts/pre-review-checks.py --all: ux-design 15/15 pass
  • markdownlint-cli2 "ux-design/**/*.md": 0 issues
  • validate-structure.sh / validate-versions.sh not run locally (need GNU tooling); relying on CI.

Assisted-by: OpenCode (Claude Opus 5.5)

@coderabbitai

coderabbitai Bot commented Nov 17, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant