Carry a prototype's display decisions into the UI Spec - #173
Merged
Merged
Conversation
A prototype reaches ui-spec-designer and stops there. Extraction is indexed by acceptance criteria, so an element no criterion names — a list row's content, a section heading, a placeholder — has no path into the spec, and the only completeness check is that every criterion has a row. "The prototype shows this and the spec omits it" was therefore undetectable, and the omission became irreversible one step later when a response contract was defined without the values the missing rendering needed. Index the check by the prototype instead: every element it renders with data or copy needs a decision. Presentation properties stay out, since they change without a requirement change and would make the document stale on every visual tweak. A prototype also does not state how far it is meant to be followed, and that answer only exists with the user. Ask for it, record it, and let it decide whether implementation tasks cite the attachment — a rough sketch handed to an implementer produces work from content the spec deliberately dropped. Then state in the design template that a contract feeding a specified display carries its values, so the loss cannot be frozen there. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Review found the attachment citation added to the task template had no supply path: a Work Plan does not cite prototypes and task decomposition is a mechanical copy, so a binding prototype would never reach an implementer. Connecting it would have meant threading the value through the plan template, the planner, the decomposer, the executor, and a reviewer. Remove the citation instead. The UI Spec already records the attachment path and its strength, and an implementer already reads the UI Spec as a governing source, so the path exists without a second one that contradicts the decomposer's copy-unchanged contract. Also scope the new completeness check to the surface already analyzed, which is where the agent's own extraction step stops — outside it the check demanded decisions about elements no requirement reaches. Declare the strength in the input contracts that carry it, and let the orchestrator resolve it from what the user has already said rather than always asking. Version 0.25.2. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
A prototype reaches
ui-spec-designerand stops there — no later stage receives its path. Extraction is indexed by acceptance criteria (agents/ui-spec-designer.md), so an element that no criterion names — a list row's content, a section heading, a placeholder — has no path into the spec. The only completeness check was "every AC has a row", which makes "the prototype shows this and the spec omits it" structurally undetectable.The omission became irreversible one step later: a Design Doc defined a response contract without the values the missing rendering needed, and every gate afterwards compares an artifact only to the one directly upstream, so each passed on a consistent-but-incomplete chain.
Changes
skills/subagents-orchestration-guide/SKILL.mdprototype_reference_strengthwhen a prototype is present, and pass it toui-spec-designer. Placed on the shared UI Spec rule so both the frontend and fullstack flows get itagents/ui-spec-designer.mdskills/documentation-criteria/references/ui-spec-template.mdskills/documentation-criteria/references/design-template.mdskills/documentation-criteria/references/task-template.mdbindingWhy the strength is asked rather than assumed
A prototype does not describe its own intended authority. One team hands over a rendering meant to be implemented as is; another a rough sketch carrying intent at unfinished quality. Only the user knows which, and the answer decides whether an implementer should see the attachment at all — handing a rough prototype to an implementer produces work from content the spec deliberately dropped.
What was deliberately not added
No new reviewer obligation.
document-reviewernever receives the prototype path, so a check there would be unexecutable;code-revieweris anchored to design-doc/work-plan by contract. Adding either would grow review surface without adding detection the author-side check does not already provide.